데이터 세트에 적합한 num_leaves 및 num_leaves_to_search의 최적 값을 찾는 데 도움이 되는 권장사항을 적용하려면 다음 단계를 따르세요.
다음 사례에 최적화된 ScaNN 색인을 만들려면 num_leaves 파라미터를 다음 값으로 설정합니다. 여기서 rows는 색인이 생성된 테이블의 행 수입니다.
균형 잡힌 색인 빌드 시간과 품질num_leaves를 sqrt(rows)로 설정합니다.
quality num_leaves를 rows/100으로 설정합니다.
목표 재현율 범위(예: 95%)에 도달할 때까지 scann.num_of_leaves_to_search 값을 늘려 테스트 쿼리를 실행합니다. 쿼리 분석에 대한 자세한 내용은 쿼리 분석을 참조하세요.
scann.num_leaves_to_search와 num_leaves 간의 비율을 기록해 둡니다. 이는 후속 단계에서 사용됩니다. 이 비율은 목표 재현율을 달성하는 데 도움이 되는 데이터 세트의 근사치를 제공합니다.
고차원 벡터(500차원 이상)로 작업하고 재현율을 개선하려면 scann.pre_reordering_num_neighbors 값을 조정해 보세요. 기본값은 500 * K로 설정됩니다. 여기서 K는 쿼리에서 설정한 한도입니다.
쿼리가 목표 재현율을 달성한 후 QPS가 너무 낮으면 다음 단계를 따르세요.
다음 안내에 따라 num_leaves 및 scann.num_leaves_to_search 값을 늘려 색인을 다시 만듭니다.
num_leaves를 행 수 제곱근의 더 큰 계수로 설정합니다. 예를 들어 색인의 num_leaves이 행 수의 제곱근으로 설정되어 있으면 제곱근의 두 배로 설정해 보세요. 값이 이미 두 배인 경우 제곱근의 세 배로 설정해 보세요.
3단계에서 기록한 num_leaves과의 비율을 유지하기 위해 필요에 따라 scann.num_leaves_to_search를 늘립니다.
num_leaves를 행 수를 100으로 나눈 값 이하로 설정합니다.
테스트 쿼리를 다시 실행합니다.
테스트 쿼리를 실행하는 동안 scann.num_leaves_to_search를 줄여 실행하면서 재현율을 높게 유지하면서 QPS를 높이는 값을 찾아보세요. 색인을 다시 빌드하지 않고 scann.num_leaves_to_search 값을 다양하게 시도해 보세요.
QPS와 재현율 범위가 모두 허용되는 값에 도달할 때까지 4단계를 반복합니다.
3단계 트리 색인
2단계 트리 ScaNN 색인에 대한 권장사항과 더불어 다음 안내를 따르세요.
권장사항을 적용하여 num_leaves 및 max_num_levels 색인 파라미터의 최적 값을 찾으려면 다음 단계를 따르세요.
성능 목표에 따라 다음 num_leaves 및 max_num_levels 조합으로 ScaNN 색인을 만듭니다.
scann.num_leaves_to_search와 num_leaves 간의 비율을 기록해 둡니다. 이는 후속 단계에서 사용됩니다. 이 비율은 목표 재현율을 달성하는 데 도움이 되는 데이터 세트에 관한 대략적인 정보를 제공합니다.
고차원 벡터(500차원 이상)로 작업하고 재현율을 개선하려면 scann.pre_reordering_num_neighbors 값을 조정해 보세요. 기본값은 500 * K로 설정됩니다. 여기서 K은 쿼리에서 설정한 한도입니다.
쿼리가 목표 재현율을 달성한 후 QPS가 너무 낮으면 다음 단계를 따르세요.
다음 안내에 따라 num_leaves 및 scann.num_leaves_to_search 값을 늘려 색인을 다시 만듭니다.
num_leaves를 power(rows, ⅔)의 더 큰 계수로 설정합니다. 예를 들어 색인의 num_leaves가 power(rows, ⅔)으로 설정된 경우 power(rows, ⅔)의 두 배로 설정해 보세요. 값이 이미 두 배인 경우 power(rows, ⅔)의 세 배로 설정해 보세요.
3단계에서 기록한 num_leaves과의 비율을 유지하기 위해 필요에 따라 scann.num_leaves_to_search를 늘립니다.
num_leaves를 rows/100 이하의 값으로 설정합니다.
테스트 쿼리를 다시 실행합니다. 테스트 쿼리를 실행하는 동안 scann.num_leaves_to_search를 줄여 실행하면서 재현율을 높게 유지하면서 QPS를 높이는 값을 찾아보세요. 색인을 다시 빌드하지 않고 scann.num_leaves_to_search 값을 다양하게 시도해 보세요.
QPS와 재현율 범위가 모두 허용되는 값에 도달할 때까지 4단계를 반복합니다.
색인 유지보수
테이블이 자주 업데이트되거나 삽입되는 경우, 재현율 정확도를 높이기 위해 기존 ScaNN 색인을 주기적으로 다시 만드는 것이 좋습니다.
색인이 빌드된 이후 색인 측정항목을 모니터링하여 벡터 분포 또는 벡터 변형의 변경사항을 확인한 다음 그에 따라 색인을 다시 만들 수 있습니다. 측정항목에 관한 자세한 내용은 벡터 색인 측정항목을 참조하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[[["\u003cp\u003e\u003ccode\u003eScaNN\u003c/code\u003e index parameters, such as \u003ccode\u003enum_leaves\u003c/code\u003e and \u003ccode\u003enum_leaves_to_search\u003c/code\u003e, should be adjusted based on whether you're creating a two-level or three-level tree index to optimize for recall and QPS.\u003c/p\u003e\n"],["\u003cp\u003eFor a two-level tree index, setting \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003esqrt(rows)\u003c/code\u003e is recommended for a balanced index build time and quality, while setting it to \u003ccode\u003erows/100\u003c/code\u003e optimizes for quality.\u003c/p\u003e\n"],["\u003cp\u003eFor a three-level tree index, it is suggested to set \u003ccode\u003emax_num_levels\u003c/code\u003e to \u003ccode\u003e2\u003c/code\u003e, and set \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003epower(rows, ⅔)\u003c/code\u003e for a balanced build or to \u003ccode\u003erows/100\u003c/code\u003e for quality.\u003c/p\u003e\n"],["\u003cp\u003eIf QPS is low after achieving target recall, you can improve it by recreating the index, increasing \u003ccode\u003enum_leaves\u003c/code\u003e, and maintaining the ratio between \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e and \u003ccode\u003enum_leaves\u003c/code\u003e while experimenting with lowering \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e to find the right balance.\u003c/p\u003e\n"],["\u003cp\u003eRegularly reindexing the existing \u003ccode\u003eScaNN\u003c/code\u003e index is advised for tables with frequent updates or insertions to maintain recall accuracy, based on monitoring index metrics for changes in vector distributions or mutations.\u003c/p\u003e\n"]]],[],null,["# Best practices for tuning ScaNN indexes\n\nSelect a documentation version: Current (16.8.0)keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/ai/best-practices-tuning-scann)\n- [16.8.0](/alloydb/omni/16.8.0/docs/ai/best-practices-tuning-scann)\n- [16.3.0](/alloydb/omni/16.3.0/docs/ai/best-practices-tuning-scann)\n- [15.12.0](/alloydb/omni/15.12.0/docs/ai/best-practices-tuning-scann)\n- [15.7.1](/alloydb/omni/15.7.1/docs/ai/best-practices-tuning-scann)\n- [15.7.0](/alloydb/omni/15.7.0/docs/ai/best-practices-tuning-scann)\n\n\u003cbr /\u003e\n\nThis page provides recommendations about how to tune AlloyDB Omni index parameters for optimal balance between recall and QPS. The recommended parameters for the Scalable Nearest Neighbor (ScaNN) index differ depending on whether you choose to build a two-level or a three-level tree index.\n\n\u003cbr /\u003e\n\nScaNN index creation\n--------------------\n\nFor more information, see the [ScaNN Index reference](/alloydb/omni/current/docs/reference/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/omni/current/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/omni/current/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 [Vector index metrics](/alloydb/omni/current/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)."]]
