Pular para o conteúdo principal

Como criar e consultar um índice de pesquisa vetorial

Este artigo descreve como criar e consultar um índice de pesquisa vetorial usando Mosaic AI Vector Search.

O senhor pode criar e gerenciar componentes de pesquisa vetorial, como um endpoint de pesquisa vetorial e índices de pesquisa vetorial, usando a interface do usuário, o Python SDK ou a API REST.

Requisitos​

A permissão para criar e gerenciar o ponto de extremidade de pesquisa vetorial é configurada usando listas de controle de acesso. Consulte Pesquisa de vetores endpoint ACLs.

Instalação​

Para usar a pesquisa vetorial SDK, o senhor deve instalá-la em seu Notebook. Use o código a seguir para instalar o pacote:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

Em seguida, use o seguinte comando para importar VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Autenticação​

Consulte Proteção e autenticação de dados.

Criar uma pesquisa vetorial endpoint​

O senhor pode criar um endpoint de pesquisa vetorial usando a interface do usuário do Databricks, o Python SDK ou a API.

Criar uma pesquisa vetorial endpoint usando a interface do usuário​

Siga estas etapas para criar um endpoint de pesquisa vetorial usando a interface do usuário.

  1. Na barra lateral esquerda, clique em computar .

  2. Clique em Vector Search tab e clique em Create .

    Criar formulário de endpoint

  3. O formulário Criar endpoint é aberto. Digite um nome para esse endpoint.

  4. Clique em Confirmar .

Criar um endpoint de pesquisa vetorial usando o Python SDK​

O exemplo a seguir usa a função create_endpoint() do SDK para criar um endpoint de pesquisa vetorial.

Python
# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

Criar um endpoint de pesquisa vetorial usando a API REST​

Consulte a documentação de referência REST API : POST /api/2.0/vector-search/endpoint.

(Opcional) Crie e configure um site endpoint para servir o modelo de incorporação​

Se o senhor optar por ter Databricks compute os embeddings, poderá usar um Foundation Model pré-configurado APIs endpoint ou criar um modelo de serviço endpoint para servir o modelo de embedding de sua escolha. Consulte Pay-per-tokens Foundation Model APIs ou Create foundation servindo modelo endpoint para obter instruções. Para obter um exemplo do Notebook, consulte Notebook examples for calling an embeddings model.

Ao configurar um embedding endpoint, Databricks recomenda que o senhor remova a seleção default de escala para zero . O endpoint de atendimento pode levar alguns minutos para aquecer, e a consulta inicial em um índice com um endpoint reduzido pode ter um tempo limite.

nota

A inicialização do índice de pesquisa de vetores pode demorar um pouco se a incorporação endpoint não estiver configurada adequadamente para o dataset. O senhor só deve usar o endpoint da CPU para pequenos conjuntos de dados e testes. Para conjuntos de dados maiores, use uma GPU endpoint para obter o desempenho ideal.

Crie um índice de pesquisa vetorial​

O senhor pode criar um índice de pesquisa vetorial usando a interface do usuário, o Python SDK ou a API REST. A interface do usuário é a abordagem mais simples.

Há dois tipos de índices:

  • O Delta Sync Index é sincronizado automaticamente com uma tabela Delta de origem, atualizando o índice de forma automática e incremental à medida que os dados subjacentes na tabela Delta são alterados.
  • O Direct Vector Access Index suporta leitura e gravação diretas de vetores e metadados. O usuário é responsável por atualizar essa tabela usando a API REST ou o Python SDK. Esse tipo de índice não pode ser criado usando a interface do usuário. O senhor deve usar a API REST ou o SDK.

Crie um índice usando a interface do usuário​

  1. Na barra lateral esquerda, clique em Catálogo para abrir a interface do Catalog Explorer.

  2. Navegue até a tabela Delta que o senhor deseja usar.

  3. Clique no botão Criar no canto superior direito e selecione Índice de pesquisa vetorial no menu suspenso.

    Botão Criar índice

  4. Use os seletores na caixa de diálogo para configurar o índice.

    caixa de diálogo de criação de índice

    Name (Nome ): Nome a ser usado para a tabela on-line no Unity Catalog. O nome exige um namespace de três níveis, <catalog>.<schema>.<name>. Somente caracteres alfanuméricos e sublinhados são permitidos.

    Primary key : Coluna a ser usada como primária key.

    endpoint : Selecione a pesquisa vetorial endpoint que o senhor deseja usar.

    Colunas a serem sincronizadas : selecione as colunas a serem sincronizadas com o índice vetorial. Se você deixar esse campo em branco, todas as colunas da tabela de origem serão sincronizadas com o índice. A coluna key primária e a coluna de origem de incorporação ou a coluna de vetor de incorporação estão sempre sincronizadas.

    Embedding source (Fonte de incorporação ): Indique se o senhor deseja que o site Databricks faça compute embeddings para uma coluna de texto na tabela Delta (compute embeddings ) ou se a tabela Delta contém embeddings pré-computados (Use existing embedding column ).

    • Se tiver selecionado computar embeddings , selecione a coluna para a qual deseja computar embeddings e o site endpoint que está servindo o modelo de embedding. Somente colunas de texto são suportadas.
    • Se você selecionou Usar coluna de incorporação existente , selecione a coluna que contém as incorporações pré-calculadas e a dimensão de incorporação. O formato da coluna de incorporação pré-computada deve ser array[float].

    Sync compute embeddings : Alterne essa configuração para salvar os embeddings gerados em uma tabela Unity Catalog. Para obter mais informações, consulte Salvar tabela de incorporação gerada.

    Modo de sincronização : contínuo mantém o índice sincronizado com segundos de latência. No entanto, ele tem um custo maior associado, pois um compute clustering é provisionamento para executar a transmissão de sincronização contínua pipeline. Tanto para Contínua quanto para Acionada , a atualização é incremental — somente os dados que foram alterados desde a última sincronização são processados.

    No modo de sincronização acionada , o senhor usa o Python SDK ou o REST API para iniciar a sincronização. Consulte Atualizar um índice Delta Sync.

  5. Quando terminar de configurar o índice, clique em Criar .

Criar índice usando o Python SDK​

O exemplo a seguir cria um Delta Sync Index com embeddings computados por Databricks.

Python
client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2"
)

O exemplo a seguir cria um Delta Sync Index com embeddings autogerenciáveis. Esse exemplo também mostra o uso do parâmetro opcional columns_to_sync para selecionar somente um subconjunto de colunas a serem usadas no índice.

Python
client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

Em default, todas as colunas da tabela de origem são sincronizadas com o índice. Para sincronizar somente um subconjunto de colunas, use columns_to_sync. As colunas primárias key e de incorporação são sempre incluídas no índice.

Para sincronizar apenas o key primário e a coluna de incorporação, o senhor deve especificá-los em columns_to_sync, conforme mostrado:

Python
index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Para sincronizar colunas adicionais, especifique-as conforme mostrado. O senhor não precisa incluir o key primário e a coluna de incorporação, pois eles são sempre sincronizados.

Python
index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

O exemplo a seguir cria um Índice de Acesso Vetorial Direto.

Python

client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name=f"{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

Criar índice usando a API REST​

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes.

Salvar tabela de incorporação gerada​

Se o Databricks gerar as incorporações, o senhor poderá salvar as incorporações geradas em uma tabela no Unity Catalog. Essa tabela é criada no mesmo esquema do índice vetorial e é vinculada a partir da página de índice vetorial.

O nome da tabela é o nome do índice de pesquisa vetorial, anexado por _writeback_table. O nome não é editável.

O senhor pode acessar e consultar a tabela como qualquer outra tabela no Unity Catalog. No entanto, você não deve descartar ou modificar a tabela, pois ela não deve ser atualizada manualmente. A tabela é excluída automaticamente se o índice for excluído.

Atualizar um índice de pesquisa vetorial​

Atualizar um índice Delta Sync​

Os índices criados com o modo de sincronização contínua são atualizados automaticamente quando a tabela Delta de origem é alterada. Se estiver usando o modo de sincronização acionada , use o Python SDK ou o REST API para iniciar a sincronização.

Python
index.sync()

Atualizar um índice de acesso direto a vetores​

O senhor pode usar o Python SDK ou a API REST para inserir, atualizar ou excluir dados de um Direct Vector Access Index.

Python
   index.upsert([{"id": 1,
       "field2": "value2",
       "field3": 3.0,
       "text_vector": [1.0, 2.0, 3.0]
       },
       {"id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1, 2.1, 3.0]
        }
        ])

Consultar uma pesquisa vetorial endpoint​

O senhor só pode consultar o endpoint de pesquisa de vetores usando o Python SDK, a API REST ou a função SQL vector_search() AI.

nota

Se o usuário que estiver consultando o endpoint não for o proprietário do índice de pesquisa vetorial, ele deverá ter os seguintes privilégios de UC:

  • USE CATALOG no catálogo que contém o índice de pesquisa vetorial.
  • USE SCHEMA no esquema que contém o índice de pesquisa vetorial.
  • SELECIONE no índice de pesquisa vetorial.

Para realizar uma pesquisa híbrida de similaridade de palavras-chave, defina o parâmetro query_type como hybrid. O valor de default é ann (vizinho mais próximo aproximado).

Python
# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

Use filtros em consultas​

Uma consulta pode definir filtros com base em qualquer coluna da tabela Delta. similarity_search retorna somente as linhas que correspondem aos filtros especificados. Os seguintes filtros são suportados:

Operador de filtro

Comportamento

Exemplos

NOT

Nega o filtro. O endereço key deve terminar com "NOT". Por exemplo, “cor NÃO” com valor “vermelho” corresponde a documentos em que a cor não é vermelha.

{"id NOT": 2} {“color NOT”: “red”}

<

Verifica se o valor do campo é menor que o valor do filtro. O endereço key deve terminar com " <". Por exemplo, “price <” com valor 200 corresponde a documentos em que o preço é menor que 200.

{"id <": 200}

<=

Verifica se o valor do campo é menor ou igual ao valor do filtro. O endereço key deve terminar com " <=". Por exemplo, “price <=” com valor 200 corresponde a documentos em que o preço é menor ou igual a 200.

{"id <=": 200}

>

Verifica se o valor do campo é maior que o valor do filtro. O endereço key deve terminar com " >". Por exemplo, “preço >” com valor 200 corresponde a documentos em que o preço é maior que 200.

{"id >": 200}

>=

Verifica se o valor do campo é maior ou igual ao valor do filtro. O endereço key deve terminar com " >=". Por exemplo, “price > =” com valor 200 corresponde a documentos em que o preço é maior ou igual a 200.

{"id >=": 200}

OR

Verifica se o valor do campo corresponde a algum dos valores do filtro. O endereço key deve conter OR para separar várias subchaves. Por exemplo, color1 OR color2 com valor ["red", "blue"] corresponde a documentos em que color1 é red ou color2 é blue.

{"color1 OR color2": ["red", "blue"]}

LIKE

Corresponde a tokens separado por espaços em branco em uma cadeia de caracteres. Veja os exemplos de código abaixo.

{"column LIKE": "hello"}

Nenhum operador de filtro especificado

O filtro verifica a correspondência exata. Se vários valores forem especificados, ele corresponderá a qualquer um dos valores.

{"id": 200} {"id": [200, 300]}

Veja os seguintes exemplos de código:

Python
# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

Exemplo de notebook​

Os exemplos desta seção demonstram o uso do Python SDK de pesquisa vetorial.

Exemplos de LangChain​

Consulte Como usar LangChain com Mosaic AI Vector Search para usar Mosaic AI Vector Search como uma integração com o pacote LangChain.

O Notebook a seguir mostra como converter os resultados da pesquisa de similaridade em documentos do site LangChain.

Pesquisa vetorial com o notebook Python SDK

Open notebook in new tab

Notebook exemplos para chamar um modelo de embeddings​

O seguinte Notebook demonstra como configurar um Mosaic AI Model Serving endpoint para a geração de embeddings.

Chame um modelo de embeddings da OpenAI usando o Mosaic AI Model Serving Notebook

Open notebook in new tab

Chame um modelo de embeddings GTE usando o Mosaic AI Model Serving Notebook

Open notebook in new tab

registrar e servir um modelo de incorporação de OSS Notebook

Open notebook in new tab
Última atualização em