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

Usar serviços de modelo

info

Beta

Este recurso está em Beta. Administradores de conta podem controlar o acesso a este recurso na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

Neste artigo, aprenderá as opções para escrever solicitações de consulta para modelos de base e enviá-las para um serviço de modelo no Gateway de AI do Unity.

O Unity AI Gateway expõe serviços de modelo por meio de uma API unificada e compatível com OpenAI, para que o usuário possa experimentar e personalizar modelos de base hospedados no Databricks em todos os provedores. Identifique um serviço de modelo pelo seu nome totalmente qualificado como o slug do modelo — por exemplo, system.ai.claude-opus-4-6— e envie solicitações para o URL base do Unity AI Gateway do seu workspace, https://<workspace-url>/ai-gateway/mlflow/v1.

nota

Os exemplos neste artigo consultam serviços de modelo. Para compatibilidade retroativa, o Databricks interpreta um nome de modelo hospedado pelo Databricks sem um nome totalmente qualificado, como databricks-claude-opus-4-6, como o serviço de modelo fornecido pelo sistema system.ai.claude-opus-4-6. Esse comportamento permite que as cargas de trabalho existentes continuem em execução sem alterações no código.

Opções de consulta​

O Unity AI Gateway oferece as seguintes opções para enviar solicitações de consulta a serviços de modelo que servem modelos de base:

Método

Detalhes

Cliente OpenAI

Consultar um serviço de modelo usando o cliente OpenAI. Especifique o nome totalmente qualificado do serviço de modelo (por exemplo, system.ai.claude-opus-4-6) como a entrada model. Suportado para modelos de chat, embeddings e conclusões disponibilizados pelas APIs de Modelo de Fundação ou modelos externos.

API REST

Chame e consulte o serviço de modelo usando a API REST. Envie uma solicitação POST para a URL base do Gateway de AI do Unity do seu workspace, https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions. Consulte Gateway de AI do Unity.

SDK Python do Databricks

O SDK Python do Databricks é uma camada sobre a API REST. Ele lida com detalhes de baixo nível, como autenticação, facilitando a interação com os modelos.

nota

Durante a versão Beta, não é possível consultar um serviço de modelo com a função SQL ai_query. Consulte serviços de modelo com o cliente OpenAI ou a API REST.

Requisitos​

  • EXECUTE no serviço de modelo, e USE CATALOG e USE SCHEMA em seu catálogo e esquema. Os serviços de modelo fornecidos pelo sistema em system.ai concedem EXECUTE a todos os usuários da account por default. Você não precisa de acesso aos modelos que o serviço referencia — o Databricks verifica se o *proprietário* do serviço de modelo tem EXECUTE neles.
  • Um serviço de modelo para consultar. Para criar um serviço de modelo personalizado, consulte Criar serviços de modelo personalizados.
  • Um workspace do Databricks em uma região suportada pelo Unity AI Gateway.
  • Para enviar uma solicitação de pontuação por meio do cliente OpenAI ou da API REST, você precisa ter um token de API do Databricks.
importante

Como prática recomendada de segurança para cenários de produção, o Databricks recomenda o uso de tokens OAuth máquina a máquina para autenticação durante a produção.

Para teste e desenvolvimento, o Databricks recomenda usar um access token pessoal pertencente a entidades de serviço em vez de usuários do workspace. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Instalar pacotes​

Após selecionar um método de consulta, você deve primeiro instalar o pacote apropriado no seu cluster.

Para usar o cliente OpenAI, o pacote databricks-openai precisa ser instalado em seu cluster. Este pacote fornece um cliente OpenAI com autorização configurada automaticamente para consultar modelos de AI generativos. Execute o seguinte em seu Notebook ou em seu terminal local:

pip install -U databricks-openai

O seguinte é necessário apenas ao instalar o pacote em um Notebook Databricks

Python
dbutils.library.restartPython()

Saídas estruturadas​

As saídas estruturadas são compatíveis com OpenAI e estão disponíveis apenas durante o servindo modelo como parte do Unity AI Gateway. Para obter detalhes, consulte Saídas estruturadas no Databricks.

Cache de prompt​

O cache de prompt é compatível com modelos Claude hospedados pelo Databricks como parte do Unity AI Gateway.

Você pode especificar o parâmetro cache_control em suas solicitações de consulta para armazenar em cache o seguinte:

  • Mensagens de conteúdo de texto na matriz messages.content.
  • Conteúdo de mensagens de raciocínio na matriz messages.content.
  • Bloqueios de conteúdo de imagens no array messages.content.
  • Uso de ferramentas, resultados e definições no array tools.
JSON
{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's the date today?",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    }
  ]
}
nota

A API REST do Databricks é compatível com OpenAI e difere da API da Anthropic. Essas diferenças também impactam objetos de resposta como os seguintes:

  • A saída é retornada no campo choices.
  • Formato de trecho de transmissão. Todos os trechos aderem ao mesmo formato, onde choices contém a resposta delta e o uso é retornado em cada trecho.
  • O motivo da interrupção é retornado no campo finish_reason.
    • Anthropic usa: end_turn, stop_sequence, max_tokens e tool_use
    • Respectivamente, o Databricks usa: stop, stop, length, e tool_calls

Converse com LLMs compatíveis utilizando o AI Playground​

Você pode interagir com grandes modelos de linguagem compatíveis utilizando o AI Playground. O AI Playground é um ambiente semelhante a um bate-papo onde você pode testar, solicitar e comparar LLMs do seu workspace Databricks.

Playground de IA

Recursos adicionais​

Nesta página