데이터 세트에 적합한 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-04(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)."]]
