Best Practices für die Optimierung von ScaNN-Indexen in AlloyDB for PostgreSQL
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Die empfohlenen Parameter für den ScaNN-Index hängen davon ab, ob Sie einen Index mit zwei oder drei Ebenen erstellen. Auf dieser Seite finden Sie Empfehlungen zum Optimieren von AlloyDB for PostgreSQL-Indexparametern, um ein optimales Gleichgewicht zwischen Recall und QPS zu erreichen.
So wenden Sie Empfehlungen an, um die optimalen Werte für num_leaves und num_leaves_to_search für Ihren Datensatz zu ermitteln:
Wenn Sie den für die folgenden Fälle optimierten Index ScaNN erstellen möchten, legen Sie den Parameter num_leaves auf den folgenden Wert fest, wobei „rows“ die Anzahl der Zeilen in der indexierten Tabelle ist:
Ausgewogene Indexerstellungszeit und ‑qualität: Setzen Sie num_leaves auf sqrt(rows).
Bei quality wird „num_leaves“ auf „rows/100“ festgelegt.
Führen Sie Ihre Testabfragen aus und erhöhen Sie den Wert von scann.num_of_leaves_to_search, bis Sie den gewünschten Recall-Bereich erreichen, z. B. 95%. Weitere Informationen zum Analysieren von Abfragen finden Sie unter Abfragen analysieren.
Notieren Sie sich das Verhältnis zwischen scann.num_leaves_to_search und num_leaves, das in den nachfolgenden Schritten verwendet wird. Dieses Verhältnis bietet eine Annäherung an den Datensatz, mit dem Sie die angestrebte Erinnerung erreichen können.
Wenn Sie mit Vektoren mit hoher Dimension (500 Dimensionen oder mehr) arbeiten und die Erinnerung verbessern möchten, versuchen Sie, den Wert von scann.pre_reordering_num_neighbors zu optimieren. Der Standardwert ist auf 500 * K festgelegt, wobei K das Limit ist, das Sie in Ihrer Abfrage festgelegt haben.
Wenn Ihre Rate von Abfragen pro Sekunde zu niedrig ist, nachdem Ihre Anfragen ein bestimmtes Ziel für den Recall erreicht haben, gehen Sie so vor:
Erstellen Sie den Index neu und erhöhen Sie den Wert von num_leaves und scann.num_leaves_to_search gemäß der folgenden Anleitung:
Setzen Sie num_leaves auf einen größeren Faktor der Quadratwurzel der Anzahl der Zeilen. Wenn der Index beispielsweise num_leaves auf die Quadratwurzel der Zeilenanzahl festgelegt hat, versuchen Sie, ihn auf das Doppelte der Quadratwurzel festzulegen. Wenn der Wert bereits verdoppelt wurde, versuchen Sie, ihn auf das Dreifache der Quadratwurzel zu setzen.
Erhöhen Sie scann.num_leaves_to_search nach Bedarf, um das Verhältnis zu num_leaves beizubehalten, das Sie in Schritt 3 notiert haben.
Legen Sie für num_leaves einen Wert fest, der kleiner oder gleich der Zeilenanzahl geteilt durch 100 ist.
Führen Sie die Testabfragen noch einmal aus.
Während Sie die Testanfragen ausführen, können Sie mit einer Reduzierung von scann.num_leaves_to_search experimentieren, um einen Wert zu finden, der die Anzahl der Abfragen pro Sekunde erhöht und gleichzeitig die Trefferquote hoch hält. Sie können verschiedene Werte für scann.num_leaves_to_search ausprobieren, ohne den Index neu erstellen zu müssen.
Wiederholen Sie Schritt 4, bis sowohl die QPS als auch der Recall-Bereich akzeptable Werte erreicht haben.
Baumindex mit drei Ebenen
Zusätzlich zu den Empfehlungen für den ScaNN-Index mit zwei Ebenen sollten Sie die folgenden Hinweise beachten.
So wenden Sie Empfehlungen an, um den optimalen Wert der Indexparameter num_leaves und max_num_levels zu ermitteln:
Erstellen Sie den ScaNN-Index mit den folgenden num_leaves- und max_num_levels-Kombinationen, die auf Ihren Leistungszielen basieren:
Indexaufbauzeit und ‑qualität in Einklang bringen: Legen Sie max_num_levels auf 2 und num_leaves auf power(rows, ⅔) fest.
Für Qualität optimieren: Legen Sie max_num_levels als 2 und num_leaves als rows/100 fest.
Führen Sie Ihre Testabfragen aus. Weitere Informationen zum Analysieren von Abfragen finden Sie unter Abfragen analysieren.
Notieren Sie sich das Verhältnis zwischen scann.num_leaves_to_search und num_leaves, das in den nachfolgenden Schritten verwendet wird. Dieses Verhältnis bietet eine Schätzung für das Dataset, mit dem Sie den angestrebten Recall erreichen können.
Wenn Sie mit Vektoren mit vielen Dimensionen (500 oder mehr) arbeiten und den Recall verbessern möchten, versuchen Sie, den Wert von scann.pre_reordering_num_neighbors zu optimieren. Der Standardwert ist auf 500 * K festgelegt, wobei K das Limit ist, das Sie in Ihrer Abfrage festgelegt haben.
Wenn Ihre Rate von Abfragen pro Sekunde zu niedrig ist, nachdem Ihre Anfragen eine Ziel-Recall-Rate erreicht haben, gehen Sie so vor:
Erstellen Sie den Index neu und erhöhen Sie den Wert von num_leaves und scann.num_leaves_to_search gemäß den folgenden Richtlinien:
Setzen Sie num_leaves auf einen größeren Faktor von power(rows, ⅔). Wenn der Index beispielsweise num_leaves auf power(rows, ⅔) gesetzt hat, versuchen Sie, ihn auf das Doppelte von power(rows, ⅔) zu setzen. Wenn der Wert bereits doppelt ist, versuchen Sie, ihn auf das Dreifache von power(rows, ⅔) zu setzen.
Erhöhen Sie scann.num_leaves_to_search nach Bedarf, um das Verhältnis zu num_leaves beizubehalten, das Sie in Schritt 3 notiert haben.
Setzen Sie num_leaves auf einen Wert, der kleiner oder gleich rows/100 ist.
Führen Sie die Testabfragen noch einmal aus. Während Sie die Testanfragen ausführen, können Sie mit einer Reduzierung von scann.num_leaves_to_search experimentieren, um einen Wert zu finden, der die Anzahl der Abfragen pro Sekunde erhöht und gleichzeitig die Trefferquote hoch hält. Sie können verschiedene Werte für scann.num_leaves_to_search ausprobieren, ohne den Index neu erstellen zu müssen.
Wiederholen Sie Schritt 4, bis sowohl die QPS als auch der Recall-Bereich akzeptable Werte erreicht haben.
Indexwartung
Wenn Ihre Tabelle häufig aktualisiert oder neue Zeilen eingefügt werden, empfehlen wir, den vorhandenen ScaNN-Index regelmäßig neu zu indexieren, um die Genauigkeit des Rückrufs zu verbessern.
Sie können Indexmesswerte beobachten, um Änderungen an Vektorverteilungen oder Vektormutationen seit der Erstellung des Index zu sehen, und dann entsprechend neu indexieren. Weitere Informationen zu Messwerten finden Sie unter Messwerte für Vektorindex ansehen.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-25 (UTC)."],[[["\u003cp\u003eThe optimal \u003ccode\u003eScaNN\u003c/code\u003e index parameters depend on whether you're building a two-level or three-level tree index, with adjustments needed for balanced build time, quality, or high-dimensional vectors.\u003c/p\u003e\n"],["\u003cp\u003eFor two-level tree indexes, set \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003esqrt(rows)\u003c/code\u003e for a balanced index or \u003ccode\u003erows/100\u003c/code\u003e for higher quality, then adjust \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e to reach your target recall, and tune both together to increase QPS if needed.\u003c/p\u003e\n"],["\u003cp\u003eFor three-level tree indexes, set \u003ccode\u003emax_num_levels\u003c/code\u003e to \u003ccode\u003e2\u003c/code\u003e and \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003epower(rows, ⅔)\u003c/code\u003e for balanced performance or \u003ccode\u003erows/100\u003c/code\u003e for high quality, and then tune \u003ccode\u003enum_leaves\u003c/code\u003e and \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e to achieve better recall and QPS.\u003c/p\u003e\n"],["\u003cp\u003eIf working with high-dimension vectors, tuning \u003ccode\u003escann.pre_reordering_num_neighbors\u003c/code\u003e can help improve recall.\u003c/p\u003e\n"],["\u003cp\u003ePeriodically reindexing the existing \u003ccode\u003eScaNN\u003c/code\u003e index is recommended for tables with frequent updates or insertions to improve the recall accuracy.\u003c/p\u003e\n"]]],[],null,["# Best practices for tuning ScaNN indexes in AlloyDB for PostgreSQL\n\nThe recommended parameters for the `ScaNN` index differ depending on\nwhether you choose to build a two-level or a three-level tree index. This page\nprovides recommendations about how to tune AlloyDB for PostgreSQL index\nparameters for optimal balance between recall and QPS.\n\nScaNN index creation\n--------------------\n\nFor more information view the [ScaNN Index reference](/alloydb/docs/reference/ai/scann-index-reference).\n\n### Two-level tree index\n\nTo apply recommendations to help you find the optimal values of `num_leaves` and `num_leaves_to_search` for your dataset,\nfollow these recommended steps:\n\n1. To create the `ScaNN` index optimized for the following cases set the `num_leaves` parameter to the following value, where rows is the number of rows in the indexed table:\n - **balanced index build time and quality** set `num_leaves` to `sqrt(rows)`.\n - **quality** set num_leaves to rows/100.\n2. Run your test queries, increasing the value of `scann.num_of_leaves_to_search`, until you achieve your target recall range--for example, 95%. For more information about analyzing your queries, see [Analyze your queries](/alloydb/docs/ai/tune-indexes?resource=scann#explain-analyze).\n3. Take note of the ratio between `scann.num_leaves_to_search` and `num_leaves` that will be used in subsequent steps. This ratio provides an approximation around the dataset that will help you achieve your target recall. \n\n If you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of `scann.pre_reordering_num_neighbors`. The default value is set to the value `500 * K` where `K` is the limit that you set in your query.\n4. If your QPS is too low after your queries achieve a target recall, then follow these steps:\n 1. Recreate the index, increasing the value of `num_leaves` and `scann.num_leaves_to_search` according to the following guidance:\n - Set `num_leaves` to a larger factor of the square root of your row count. For example, if the index has `num_leaves` set to the square root of your row count, try setting it to double the square root. If the value is already double, then try setting it to triple the square root.\n - Increase `scann.num_leaves_to_search` as needed to maintain its ratio with `num_leaves`, which you noted in Step 3.\n - Set `num_leaves` to a value less than or equal to the row count divided by 100.\n 2. Run the test queries again. While you're running the test queries, experiment with reducing `scann.num_leaves_to_search`, finding a value that increases QPS while keeping your recall high. Try different values of `scann.num_leaves_to_search` without rebuilding the index.\n5. Repeat Step 4 until both the QPS and the recall range have reached acceptable values.\n\n### Three-level tree index\n\nIn addition to the recommendations for the two-level tree `ScaNN` index, use the following guidance.\n\nTo apply recommendations to find the optimal value of `num_leaves` and `max_num_levels` index parameters, follow these steps:\n\n1. Create the `ScaNN` index with the following `num_leaves` and `max_num_levels` combinations based on your performance goals:\n\n - **balance index build time \\& quality** : Set `max_num_levels` as `2` and `num_leaves` as `power(rows, ⅔)`.\n - **optimize for quality** : Set `max_num_levels` as `2` and `num_leaves` as `rows/100`.\n2. Run your test queries. For more information about analyzing queries, see [Analyze your queries](/alloydb/docs/ai/tune-indexes?resource=scann#explain-analyze).\n\n3. Take note of the ratio between `scann.num_leaves_to_search` and `num_leaves` that will be used in subsequent steps. This ratio provides an approximation around the dataset that will help you achieve your target recall.\n\nIf you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of `scann.pre_reordering_num_neighbors`. The default value is set to the value `500 * K` where `K` is the limit that you set in your query.\n\n1. If your QPS is too low after your queries achieve a target recall, then follow these steps:\n\n - Recreate the index, increasing the value of `num_leaves` and `scann.num_leaves_to_search` according to the following guidance:\n - Set `num_leaves` to a larger factor of the `power(rows, ⅔)`. For example, if the index has `num_leaves` set to the `power(rows, ⅔)`, try setting it to double the `power(rows, ⅔)`. If the value is already double, then try setting it to triple the `power(rows, ⅔)`.\n - Increase `scann.num_leaves_to_search` as needed to maintain its ratio with `num_leaves`, which you noted in Step 3.\n - Set `num_leaves` to a value less than or equal to `rows/100`.\n - Run the test queries again. While you're running the test queries, experiment with reducing `scann.num_leaves_to_search`, finding a value that increases QPS while keeping your recall high. Try different values of `scann.num_leaves_to_search` without rebuilding the index.\n2. Repeat Step 4 until both the QPS and the recall range have reached acceptable values.\n\nIndex maintenance\n-----------------\n\nIf your table is prone to frequent updates or insertions, then we recommend periodically reindexing the existing `ScaNN` index in order to improve the recall accuracy.\nYou can monitor index metrics to view changes in vector distributions or vector mutations since the index was built, and then reindex accordingly. For more information about metrics, see [View Vector index metrics](/alloydb/docs/reference/vector-index-metrics).\n\nWhat's next\n-----------\n\n- [Get started with vector embeddings using AlloyDB AI](https://codelabs.developers.google.com/alloydb-ai-embedding#0)."]]
