Pular para o conteúdo principal
Última atualização em

Dimensionar a taxa de transferência do endpoint de Pesquisa de IA com QPS alto

Por default, endpoints padrão suportam 20–200 QPS dependendo do tamanho do índice. Aplicações em tempo real, como barras de pesquisa, sistemas de recomendação e correspondência de entidades, frequentemente exigem 100 a 1.000+ QPS. Somente em endpoints padrão, é possível definir um QPS alvo. A Databricks provisiona a infraestrutura para melhor corresponder àquele nível de taxa de transferência (melhor esforço, não garantido).

importante

A definição de um QPS alvo provisiona capacidade adicional, o que aumenta o custo do endpoint. É cobrado por essa capacidade adicional independentemente do tráfego real de query. O escalonamento de throughput é de melhor esforço e não é garantido.

Usar alta QPS quando:

  • Seu aplicativo requer mais de 50 QPS de taxa de transferência sustentada.
  • Você recebe erros 429 (excesso de solicitações) sob carga normal.
  • A latência é comprometida com o aumento do tráfego, mesmo quando a utilização média aparenta ser baixa.

Requisitos​

  • Alta QPS está disponível apenas para endpoints padrão. Endpoints otimizados para armazenamento não são suportados.

  • Use a autenticação OAuth para entidade de serviço e o URL do índice para cargas de trabalho de produção de alto QPS. Tokens de acesso pessoal (PATs) e o URL de consulta do workspace são apropriados para prototipagem, mas não usam a rota de consulta otimizada e são limitados a algumas dezenas de QPS.

  • Se o workspace tiver um objeto de configurações de acesso privado anexado, nenhum índice no workspace poderá usar a rota de query otimizada, independentemente do tipo de índice ou das configurações do objeto.

    • Os Workspace que usam o Private Service Connect para conectividade de front-end ou back-end têm um objeto de configurações de acesso privado.
    • Nessa configuração, as queries usam a URL de query do workspace, que é limitada a algumas dezenas de QPS, portanto, o endpoint não pode atingir um alvo de QPS mais alto.
    • Para cargas de trabalho de alto QPS, use um workspace que não tenha um objeto de configurações de acesso privado anexado. Se você não puder usar um workspace diferente, entre em contato com sua equipe de account do Databricks.

  • Os índices de sincronização Delta que usam modelos de incorporação gerenciados não podem usar a rota de query otimizada se o workspace tiver o recurso de lista de acesso IP habilitado.

    • Nessa configuração, as queries ao índice usam a URL de query do workspace, que é limitada a algumas dezenas de QPS, portanto o endpoint não pode atingir um alvo de QPS mais alto. Isso se aplica a todas as queries ao índice, incluindo queries que passam query_vector.
    • : Em um workspace sem um objeto de configurações de acesso privado, use incorporações autogerenciadas para atingir seu QPS de destino: um índice de sincronização Delta com uma coluna de vetor de incorporação ou um índice de acesso vetorial direto. : Consulte opções para fornecer incorporações.

Configurar QPS alvo​

Defina um QPS alvo ao criar um novo endpoint ou ao atualizar um existente. A capacidade adicional necessária para melhor corresponder ao throughput alvo é provisionada automaticamente. O escalonamento de throughput é de melhor esforço e não é garantido: o QPS real depende do tamanho do índice, dimensionalidade do vetor, complexidade da query e uso do filtro.

Ao criar um novo endpoint:

  1. Na barra lateral esquerda, clique em Compute .

  2. Clique na tab Pesquisa de IA e clique em Criar endpoint .

    Criar compute de pesquisa de IA.

  3. Em Configurações avançadas , insira o valor de QPS alvo .

    Crie a caixa de diálogo do endpoint de Pesquisa de AI.

Ao atualizar um endpoint existente:

  1. Acesse a página de detalhes do endpoint.

  2. No painel direito, clique no ícone de lápis Ícone de lápis. ao lado de **QPS alvo**.

    Editar QPS alvo.

  3. Insira o novo valor e clique em Salvar .

    Insira o valor de QPS de destino.

Configurar um Service Principal​

As consultas de alto QPS precisam de um token OAuth com authorization_details para o índice. Use um service principal para produção. Para configurar o service principal:

  1. Adicione uma Service Principal e atribua-a ao Workspace que contém o índice.

  2. Criar um segredo OAuth para o Service Principal:

    • Siga os passos em Criar um segredo do OAuth.
    • Em Escopos , selecione todas as APIs . O Python SDK solicita o escopo all-apis, e um token não pode exceder os escopos de seu segredo, portanto, um segredo limitado a escopos mais restritos não pode obter um token para o SDK. O exemplo REST também solicita all-apis. Esse escopo torna o segredo amplo, portanto, use um service principal dedicado que tenha apenas as concessões nesta página.
    • Armazene o ID do cliente e o segredo em um Secret Scope em vez de no código do seu aplicativo.

  3. Conceda à Service Principal os seguintes privilégios do Unity Catalog:

    • USE CATALOG no catálogo que contém o índice.
    • USE SCHEMA no esquema que contém o índice.
    • SELECIONE no índice.
    • SELECT e MODIFY no índice, se o service principal fizer upsert ou excluir dados em um índice de acesso vetorial direto.

    Se o service principal possuir o índice, ele não precisará de SELECT ou MODIFY, mas ainda precisará de USE CATALOG e USE SCHEMA.

  4. Para um índice que usa um modelo de incorporação gerenciar pelo Databricks, conceda permissões no Endpoint de servindo modelo de incorporação e, se o índice definir model_endpoint_name_for_query, nesse endpoint também. A permissão necessária depende do tipo de endpoint:

    • Endpoint de APIs do Foundation Model pay-per-token , como databricks-gte-large-en: Nenhuma concessão é necessária, a menos que sua account restrinja os modelos de base com permissões do Unity Catalog. Nesse caso, conceda EXECUTE no modelo.
    • throughput provisionada e endpoints de serviço personalizados : Conceda Can Query para query com query_text. Conceda pelo menos Can View mesmo que você query apenas com query_vector e use o Python SDK, porque get_index() lê esses Endpoint de serviço e falha sem permissão.

Fazer query de um índice não requer nenhuma permissão no próprio Endpoint de Pesquisa de AI.

A Service Principal autentica com autorização OAuth máquina a máquina (M2M). O token OAuth deve incluir authorization_details que permitam ReadVectorIndex no índice, ou WriteVectorIndex para upserts e deletes.

Se o Endpoint de servindo modelo de incorporação ou o Endpoint model_endpoint_name_for_query estiver otimizado para rota, o token também precisará de uma entrada workspace_permission que permita query_inference_endpoint em cada um. Para verificar se um endpoint de serviço está otimizado para rota, consulte o campo route_optimized retornado por GET /api/2.0/serving-endpoints/<name>.

  • Python SDK : passe o ID do cliente e o segredo para AISearchClient, conforme mostrado em query o URL do índice. O SDK solicita um tokens com o authorization_details necessário e adiciona as entradas do Endpoint de atendimento automaticamente. Para um Endpoint model_endpoint_name_for_query otimizado para rotas, isso requer databricks-ai-search 0.79 ou acima.
  • API REST : Solicite o token você mesmo. Consulte o exemplo de Service Principal na tab API REST de Como fazer query de um índice de Pesquisa de AI.

Para testes, você também pode usar um tokens obtido por meio da troca de tokens de notebook. Use um service principal para produção.

nota

Alterações de privilégio se aplicam apenas a tokens recém-emitidos. Revogar um privilégio não invalida um token que já foi emitido. Esse tokens permanece válido até expirar, o que leva até uma hora. Com o Python SDK, chame get_index() novamente depois de alterar os privilégios ou a configuração do endpoint de incorporação. Os chamadores de REST devem solicitar um novo token.

query o URL do índice​

Depois que o estado de dimensionamento do Endpoint for SCALING_CHANGE_APPLIED, envie query para o URL do índice usando tokens OAuth com authorization_details para o índice, como um token de service principal. Este URL é necessário para usar a capacidade de query adicional com provisionamento por target_qps.

Para aplicativos Python, chame get_index() uma vez e reutilize o objeto de índice retornado. O Python SDK envia queries para a URL do Índice.

Python
from databricks.ai_search.client import AISearchClient

client = AISearchClient(
    service_principal_client_id="...",
    service_principal_client_secret="...",
    workspace_url="https://<workspace-url>",
)

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

# Reuse this index object for every query.
index.similarity_search(query_vector=[...], columns=["id", "text"], num_results=10)

Para aplicações REST ou que não sejam Python, primeiro obtenha o URL do índice e, em seguida, envie solicitações de query para esse URL. O token deve ser um token OAuth com authorization_details para o índice. Use um Service Principal para produção.

sh
export WORKSPACE_URL=https://<workspace-url>
export INDEX_NAME=catalog.schema.index
export TOKEN=<oauth-token>

export INDEX_URL=$(curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "$WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME" \
  | jq -r '.status.index_url')

case "$INDEX_URL" in
  http://*|https://*) ;;
  *) INDEX_URL="https://$INDEX_URL" ;;
esac

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$INDEX_URL/query" \
  --data '{"num_results": 10, "query_vector": [...], "columns": ["id", "text"]}'

Não use o URL de query do workspace, como /api/2.0/vector-search/indexes/<index_name>/query, para tráfego de produção de alto QPS. Esse URL não usa a rota de consulta otimizada e pode retornar erros 429 antes que o endpoint atinja o QPS de destino configurado.

Como o dimensionamento se aplica​

Após definir um QPS de destino, a capacidade necessária é provisionada automaticamente. O novo nível de Taxa de transferência se aplica após o provisionamento ser concluído; não é necessário sincronizar os índices para acionar a alteração.

nota

A tentativa de atualizar o QPS alvo enquanto uma operação de escalonamento está em andamento retorna um erro RESOURCE_CONFLICT. Aguarde a conclusão da operação atual antes de tentar novamente.

Solucionar problemas de erros 429​

Para cargas de trabalho de alto QPS, use estas verificações para encontrar o gargalo:

Limitações​

  • No autoscale : é preciso definir o QPS alvo manualmente com base no tráfego esperado. Se o tráfego exceder o nível de provisionamento, erros 429 ocorrerão. Ver Plano para picos de consulta
  • Somente endpoints padrão: endpoints otimizados para armazenamento não target_qps suportam.
  • Rota otimizada necessária : o QPS de destino configurado se aplica ao tráfego que usa autenticação OAuth de entidade de serviço e o URL do índice. O tráfego PAT e o tráfego de URL de consulta do workspace são limitados a algumas dezenas de QPS.
  • Modelos de incorporação gerenciados podem adicionar um segundo limite : para índices Delta Sync que usam um modelo de incorporação gerenciado para consultas de texto, a taxa de transferência de consulta também depende do endpoint de servindo modelo de incorporação. Aumente a capacidade de servindo modelo, use taxa de transferência provisionada ou use incorporações autogerenciadas para uma taxa de transferência de consulta previsível.
Nesta página