Ajustar um reclassificador de busca de AI

info

Beta

Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

O ajuste fino do reclassificador treina um reclassificador personalizado nos dados do seu próprio índice e, em seguida, o disponibiliza para que um modelo ajustado ao seu corpus reclassifique suas queries. O Databricks lida com a geração de dados de treinamento, treinamento de modelo, registro no Unity Catalog e implantação em um endpoint de Model Serving para você.

Este recurso é compatível apenas com índices gerenciados. Índices gerenciados são índices de sincronização Delta onde o Databricks compute as incorporações.

Requisitos

• Um índice de Pesquisa de AI de sincronização Delta com incorporações gerenciadas pelo Databricks. Índices de acesso direto e índices com incorporações autogerenciadas não são compatíveis. Consulte Criar Endpoint e índices de Pesquisa de IA.
• O recurso deve estar habilitado para seu Workspace. Os administradores do Workspace podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.
• Este recurso está disponível apenas nas seguintes regiões:
  • us-west-2
  • us-west-1
  • us-east-1
  • us-east-2

Permissões

O Job de ajuste fino entra em execução como você e cria vários objetos do Unity Catalog em seu nome, portanto, você deve possuir todos os seguintes privilégios do Unity Catalog antes de começar um Job:

• SELECT no índice, para ler seus documentos para treinamento.
• CREATE VOLUME e CREATE TABLE no catálogo e esquema do índice, para o volume de dados de treinamento e tabelas intermediárias.
• CREATE MODEL no esquema onde o modelo com ajuste fino está registrado. Este é o esquema do nome do seu modelo, caso tenha definido um; caso contrário, é o próprio esquema do índice.

Se você não tiver nenhum desses privilégios, o Databricks rejeitará a solicitação com um erro de permissão em vez de iniciar um job que falharia posteriormente.

Como funciona o ajuste fino do reclassificador

O ajuste fino do reorganizador executa o seguinte pipeline em seus dados:

1. Gerar dados de treinamento. Você começa um Job de otimização em um índice. O Databricks faz a amostragem de queries a partir de seus logs de payload, de uma tabela fornecida por você ou de queries sintetizadas a partir de seus dados. Em seguida, ele recupera candidatos e usa um LLM para julgar a relevância e criar dados de treinamento.
2. Ensine o reclassificador. O Databricks treina um reclassificador nesses dados, começando a partir de um modelo de reclassificador base.
3. Registrar e implantar. O resultado é registrado como um modelo no Unity Catalog e implantado em um endpoint do Model Serving, ambos criados automaticamente.
4. Faça uma query no índice. Você faz uma query no índice com o reorganizador ajustado por meio do Python SDK ou da API REST.

Começar um job de ajuste fino

O ajuste fino do reorganizador está disponível na página de detalhes do índice vetorial no Catalog Explorer.

1. No Explorador de Catálogos, vá até seu índice vetorial e abra a tab Visão geral . Role até a seção Ajuste do reorganizador .

   

2. Clique em Execução ajuste fino do reclassificador . Se você já fez uma execução de ajuste fino anteriormente, este botão exibe Executar nova execução de ajuste fino e é habilitado após a conclusão da execução anterior.

3. Na caixa de diálogo Configurar ajuste do reorganizador , revise e preencha os seguintes campos:

   

   • Nome do modelo : o nome no Unity Catalog para o modelo ajustado. Isto está pré-preenchido como catalog.schema.reranker_<index>. Edite-o se desejar um nome diferente.

   • Origem da query de treinamento : De onde vêm as queries de treinamento:

     • Usar tabela de logs de payload : usa os logs de query capturados do seu índice. O Databricks seleciona isso por default quando uma tabela de logs de payload existe.
     • Gerar a partir de documentos de índice : a Databricks sintetiza queries a partir dos dados do seu índice.
     • De uma tabela Delta : Clique em Select table para selecionar uma tabela Delta de queries, e então, opcionalmente, selecione a Query column . A coluna de query usa query_text como default.

   • Configurações avançadas (opcional): Expanda para definir Max queries , o limite de quantas queries usar para treinamento. O valor default é 5000. Se sua tabela de query tiver menos queries do que o limite, o Databricks gera mais para alcançá-lo.

4. Clique em Começar ajuste fino . A caixa de diálogo é fechada e uma confirmação de Ajuste fino do reclassificador iniciado aparece.

Acompanhar o progresso do ajuste fino

Após começar um Job, a seção Ajuste do reorganizador mostra um Status :

Status	Descrição
Iniciando...	O job está na fila.
Executando ajuste fino…	O treinamento está em andamento.
Concluído	O reorganizador ajustado está registrado e implantado, pronto para fazer query.
Falhou	O treinamento não foi concluído. Uma mensagem de erro é exibida.

Status	Descrição
Iniciando...	O job está na fila.
Executando ajuste fino…	O treinamento está em andamento.
Concluído	O reorganizador ajustado está registrado e implantado, pronto para fazer query.
Falhou	O treinamento não foi concluído. Uma mensagem de erro é exibida.

O status refresh automaticamente. Quando o job for concluído, um link View model aparecerá para que você possa abrir o modelo de reclassificação implantado.

Consultar com o reclassificador com ajuste fino

Após o sucesso do treinamento, faça uma query no seu índice com o reorganizador ajustado usando o SDK do Python ou a API REST. Para orientações gerais sobre query, consulte Fazer query em um índice de Pesquisa de AI.

query com o Python SDK

Consulte seu índice com o databricks-ai-search Python SDK.

Python

from databricks.ai_search.client import AISearchClient
from databricks.ai_search.reranker import ExperimentalDatabricksFinetunedReranker

client = AISearchClient()
index = client.get_index(
    endpoint_name="my-endpoint",
    index_name="catalog.schema.my_index",
)

results = index.similarity_search(
    query_text="How do I create an AI Search index?",
    columns=["id", "text"],
    num_results=10,
    reranker=ExperimentalDatabricksFinetunedReranker(
        columns_to_rerank=["text"],  # must be exactly the embedding source column
    ),
)

• columns_to_rerank: Deve ser exatamente a coluna de origem de incorporação do índice, como uma lista de elemento único.
• O Endpoint de servindo modelo é resolvido automaticamente a partir do seu índice. Para direcionar a um endpoint específico, passe endpoint_name="...".

Para confirmar que o reclassificador foi executado, passe debug_level=1 e inspecione o resultado:

Python

results = index.similarity_search(..., debug_level=1)

dbg = results.get("debug_info", {})
if "warnings" in dbg:
    print("Reranker fell back:", dbg["warnings"])
else:
    print(f"Reranker ran, took {dbg['reranker_time']}ms")

query com a API REST

Você também pode fazer query com o reorganizador ajustado via REST. Envie um POST para o endpoint de query do índice com um bloco reranker. No bloco, defina model como o nome do endpoint do Model Serving ajustado, model_type como MODEL_TYPE_FINETUNED e parameters.columns_to_rerank como a coluna de origem de embedding:

Bash

curl -X POST \
  https://<workspace-host>/api/2.0/vector-search/indexes/catalog.schema.my_index/query \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "How do I create an AI Search index?",
    "columns": ["id", "text"],
    "num_results": 10,
    "debug_level": 1,
    "reranker": {
      "model": "<finetuned-endpoint-name>",
      "model_type": "MODEL_TYPE_FINETUNED",
      "parameters": {
        "columns_to_rerank": ["text"]
      }
    }
  }'

• model: O nome do endpoint do Model Serving que hospeda o reclassificador com ajuste fino, criado pelo job de ajuste fino. Ao contrário do Python SDK, a API REST não deriva isso para você.
• parameters.columns_to_rerank: Deve ser exatamente a coluna de origem de embedding do índice, a mesma regra do SDK.
• debug_level: 1 exibe debug_info.reranker_time, ou debug_info.warnings no fallback, na resposta.

Limitações

• O ajuste fino (finetuning) do Reranker é compatível apenas com índices de sincronização Delta com incorporações gerenciadas pelo Databricks. Não é possível realizar o ajuste fino (finetuning) de índices de acesso direto e de incorporações autogerenciadas.
• O Endpoint de serviço escala para zero, portanto, a primeira query após um período de inatividade sofre um atraso de início a frio. Você pode desativar a escala para zero.
• A reclassificação é fixada na coluna de origem de incorporações. Ao realizar uma query com um reclassificador ajustado, columns_to_rerank deve ser exatamente a coluna de origem de incorporações do índice, a coluna na qual o reclassificador foi treinado. O Databricks rejeita a reclassificação de qualquer outra coluna ou conjunto de colunas.