Os valores mais adequados para as opções de índice vetorial dependem do seu caso de uso, do conjunto de dados de vetores e dos vetores de consulta. É possível definir e ajustar esses valores
criando um novo índice de vetor e definindo index_option_list
na instrução CREATE VECTOR INDEX. Talvez seja necessário fazer um ajuste iterativo para encontrar os melhores valores para sua carga de trabalho específica.
Confira algumas diretrizes úteis para escolher valores adequados:
tree_depth (nível da árvore): se a tabela que você está indexando tiver menos de 10 milhões de linhas, use um tree_depth de 2. Caso contrário, um tree_depth de 3
aceita tabelas de até 10 bilhões de linhas.
num_leaves: use a raiz quadrada do número de linhas no conjunto de dados. Um valor maior pode aumentar o tempo de criação do índice de vetor. Evite definir num_leaves maior que table_row_count dividido por 1.000, porque isso resulta em folhas muito pequenas e desempenho ruim.
num_leaves_to_search: essa opção especifica quantos nós folha do índice são pesquisados. Aumentar num_leaves_to_search melhora o recall, mas também aumenta a latência e o custo. Recomendamos usar um número que seja 1% do número total de folhas definidas na instrução CREATE VECTOR INDEX como o valor de num_leaves_to_search. Se você estiver usando uma cláusula de filtro, aumente esse valor para ampliar a pesquisa.
Se um recall aceitável for alcançado, mas o custo da consulta for muito alto, resultando em um QPS máximo baixo, tente aumentar num_leaves seguindo estas etapas:
Defina num_leaves como um múltiplo k do valor original (por exemplo, 2 * sqrt(table_row_count)).
Defina num_leaves_to_search como o mesmo múltiplo k do valor original.
Tente reduzir num_leaves_to_search para melhorar o custo e o QPS, mantendo o recall.
Melhorar a recuperação
Para melhorar o recall, ajuste o valor de num_leaves_to_search ou recrie o índice de vetor.
Aumentar o valor de num_leaves_to_search
Se o valor de num_leaves_to_search for muito pequeno, talvez seja mais difícil encontrar os vizinhos mais próximos para alguns vetores de consulta. Criar um novo índice vetorial com um valor num_leaves_to_search maior pode ajudar a melhorar o recall pesquisando mais folhas. As consultas recentes podem conter mais desses vetores desafiadores.
Recriar o índice de vetor
A estrutura de árvore do índice de vetor é otimizada para o conjunto de dados no momento da criação e permanece estática depois disso. Portanto, se vetores significativamente diferentes forem adicionados após a criação do índice de vetor inicial, a estrutura de árvore poderá ser inadequada, resultando em uma recuperação mais baixa.
Para recriar o índice de vetores sem inatividade:
Crie um novo índice vetorial na mesma coluna de embedding do índice vetorial atual, atualizando os parâmetros (por exemplo, OPTIONS) conforme necessário.
Depois que a criação do índice for concluída, use a dica FORCE_INDEX
para apontar para o novo índice e atualizar a consulta de pesquisa vetorial. Isso garante
que a consulta use o novo índice de vetor. Talvez também seja necessário ajustar num_leaves_to_search na nova consulta.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-05 UTC."],[],[],null,["# Vector indexing best practices\n\n| **PostgreSQL interface note:** The examples in this topic are intended for GoogleSQL-dialect databases. This feature doesn't support PostgreSQL interface.\n\n\u003cbr /\u003e\n\n\n| **Note:** This feature is available with the Spanner Enterprise edition and Enterprise Plus edition. For more information, see the [Spanner editions overview](/spanner/docs/editions-overview).\n\n\u003cbr /\u003e\n\nThis page describes vector indexing best practices that optimize your\n[vector indexes](/spanner/docs/vector-indexes) and improve\n[approximate nearest neighbor (ANN) query results](/spanner/docs/find-approximate-nearest-neighbors#query-vector-embeddings).\n\nTune the vector search options\n------------------------------\n\nThe most optimal values for your vector index options depend on your use case,\nvector dataset, and on the query vectors. You can set and tune these values\nby creating a new vector index and setting the [`index_option_list`](/spanner/docs/reference/standard-sql/data-definition-language#index_option_list)\nin the `CREATE VECTOR INDEX` statement. You might need to perform iterative\ntuning to find the best values for your specific workload.\n\nHere are some helpful guidelines to follow when picking appropriate values:\n\n- `tree_depth` (tree level): If the table you're indexing has fewer than 10\n million rows, use a `tree_depth` of `2`. Otherwise, a `tree_depth` of `3`\n supports tables of up to about 10 billion rows.\n\n- `num_leaves`: Use the square root of the number of rows in the dataset. A\n larger value can increase vector index build time. Avoid setting `num_leaves`\n larger than the `table_row_count` divided by 1000 as this results in overly\n small leaves and poor performance.\n\n- `num_leaves_to_search`: This option specifies how many leaf nodes of the index\n are searched. Increasing `num_leaves_to_search` improves recall but also\n increases latency and cost. We recommend using a number that is 1% the total\n number of leaves defined in the `CREATE VECTOR INDEX` statement as the value\n for `num_leaves_to_search`. If you're using a filter clause, increase\n this value to widen the search.\n\nIf acceptable recall is achieved, but the cost of querying is too high,\nresulting in low maximum QPS, try increasing `num_leaves` by following these\nsteps:\n\n1. Set `num_leaves` to some multiple k of its original value (for example, `2 * sqrt(table_row_count)`).\n2. Set `num_leaves_to_search` to be the same multiple k of its original value.\n3. Experiment with reducing `num_leaves_to_search` to improve cost and QPS while maintaining recall.\n\nImprove recall\n--------------\n\nTo improve recall, consider tuning the `num_leaves_to_search` value or\nrebuilding your vector index.\n\n### Increase the `num_leaves_to_search` value\n\nIf the `num_leaves_to_search` value is too small, you might find it more\nchallenging to find the nearest neighbors for some query vectors. Creating a new\nvector index with an increased `num_leaves_to_search` value can help improve\nrecall by searching more leaves. Recent queries might contain more of these\nchallenging vectors.\n\n### Rebuild the vector index\n\nThe tree structure of the vector index is optimized for the dataset at the time\nof creation, and is static thereafter. Therefore, if significantly different\nvectors are added after creating the initial vector index, then the tree\nstructure might be sub-optimal, leading to poorer recall.\n\nTo rebuild your vector index without downtime:\n\n1. Create a new vector index on the same embedding column as the current vector index, updating parameters (for example, `OPTIONS`) as appropriate.\n2. After the index creation completes, use the [`FORCE_INDEX` hint](/spanner/docs/secondary-indexes#index-directive) to point at the new index to update the vector search query. This ensures that the query uses the new vector index. You might also need to retune `num_leaves_to_search` in your new query.\n3. Drop the outdated vector index.\n\nWhat's next\n-----------\n\n- Learn more about Spanner [vector indexes](/spanner/docs/vector-indexes).\n\n- Learn more about Spanner [approximate nearest neighbors](/spanner/docs/find-approximate-nearest-neighbors).\n\n- Learn more about the [GoogleSQL `APPROXIMATE_COSINE_DISTANCE()`, `APPROXIMATE_EUCLIDEAN_DISTANCE()`, `APPROXIMATE_DOT_PRODUCT()`](/spanner/docs/reference/standard-sql/mathematical_functions) functions.\n\n- Learn more about the [GoogleSQL `VECTOR INDEX` statements](/spanner/docs/reference/standard-sql/data-definition-language#vector_index_statements)."]]