Implantar um agente para aplicativo de IA generativa
Importante
Esta funcionalidade está em Pré-visualização Pública.
Este artigo mostra como implantar seu agente de IA usando a deploy()
função da API Python do Agent Framework.
Requisitos
MLflow 2.13.1 ou superior para implantar agentes usando a
deploy()
API dodatabricks.agents
.Registre um agente de IA no Unity Catalog. Consulte Registrar o agente no Unity Catalog.
A implantação de agentes de fora de um bloco de anotações Databricks requer
databricks-agents
SDK versão 0.12.0 ou superior.Instale o
databricks-agents
SDK.%pip install databricks-agents dbutils.library.restartPython()
Implantar um agente usando deploy()
A função deploy() faz o seguinte:
Cria um modelo de CPU servindo pontos de extremidade para seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
- Para reduzir o custo de pontos de extremidade ociosos (às custas do aumento do tempo para atender consultas iniciais), você pode habilitar a escala para zero para seu ponto de extremidade de serviço passando
scale_to_zero_enabled=True
paradeploy()
. Consulte Expectativas de dimensionamento de endpoint. - Permite tabelas de inferência com o AI Gateway no endpoint de serviço do modelo. Veja monitorizar modelos servidos usando tabelas de inferência ativadas pelo AI Gateway.
Nota
Para logs de resposta de streaming, apenas campos e rastreamentos compatíveis com ChatCompletion são agregados.
- O Databricks fornece automaticamente credenciais temporárias de serviço para o código do agente em execução no ponto de extremidade. As credenciais têm as permissões mínimas para acessar recursos gerenciados pelo Databricks, conforme definido durante o registro em log do modelo. Antes de gerar essas credenciais, o Databricks garante que o proprietário do ponto de extremidade tenha as permissões apropriadas para evitar o escalonamento de privilégios e o acesso não autorizado. Consulte Autenticação para recursos dependentes.
- Se você tiver dependências de recursos que não são gerenciadas por Databricks, por exemplo, usando o Pinecone, poderá passar variáveis de ambiente com segredos para a API
deploy()
. Consulte Configurar o acesso a recursos a partir de pontos de extremidade de serviço de modelo.
- Se você tiver dependências de recursos que não são gerenciadas por Databricks, por exemplo, usando o Pinecone, poderá passar variáveis de ambiente com segredos para a API
- Para reduzir o custo de pontos de extremidade ociosos (às custas do aumento do tempo para atender consultas iniciais), você pode habilitar a escala para zero para seu ponto de extremidade de serviço passando
Habilita o aplicativo Avaliações para seu agente. O Aplicativo de Revisão permite que as partes interessadas conversem com o agente e deem feedback usando a interface do usuário do Aplicativo de Revisão.
Registra todas as solicitações no aplicativo de revisão ou na API REST em uma tabela de inferência. Os dados registrados incluem solicitações de consulta, respostas e dados de rastreamento intermediários do MLflow Tracing.
Cria um modelo de feedback com o mesmo catálogo e esquema do agente que você está tentando implantar. Esse modelo de feedback é o mecanismo que torna possível aceitar comentários do aplicativo Review e registrá-los em uma tabela de inferência. Esse modelo é servido no mesmo modelo de CPU que serve o ponto de extremidade do seu agente implantado. Como este endpoint de serviço tem tabelas de inferência habilitadas, é possível registar feedback da aplicação de revisão em uma tabela de inferência.
Nota
As implantações podem levar até 15 minutos para serem concluídas. As cargas úteis JSON brutas levam de 10 a 30 minutos para chegar, e os logs formatados são processados a partir das cargas brutas a cada hora.
from databricks.agents import deploy
from mlflow.utils import databricks_utils as du
deployment = deploy(model_fqn, uc_model_info.version)
# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint
# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url
Tabelas de inferência aprimoradas por agente
O deploy()
cria três tabelas de inferência para cada implantação para registrar solicitações e respostas de e para o agente que serve o ponto de extremidade. Os utilizadores podem esperar que os dados estejam na tabela de dados dentro de uma hora após a interação com a sua implementação.
Os logs de solicitação de carga útil e os logs de avaliação podem levar mais tempo para serem preenchidos, mas, em última análise, são derivados da tabela de carga bruta. Você mesmo pode extrair logs de solicitação e avaliação da tabela de carga útil. As exclusões e atualizações da tabela de carga útil não são refletidas nos logs de solicitação de carga útil ou nos logs de avaliação de carga útil.
Nota
Se tiver o Firewall de Armazenamento do Azure habilitado, entre em contato com a sua equipa de conta do Databricks para habilitar tabelas de inferência para os seus endpoints.
Tabela | Exemplo de nome da tabela do Catálogo Unity | O que há em cada tabela |
---|---|---|
Payload | {catalog_name}.{schema_name}.{model_name}_payload |
Cargas úteis brutas de solicitação e resposta JSON |
Registos de pedidos de carga útil | {catalog_name}.{schema_name}.{model_name}_payload_request_logs |
Solicitações e respostas formatadas, rastreamentos MLflow |
Logs de avaliação de carga útil | {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs |
Comentários formatados, conforme fornecidos no aplicativo Avaliações, para cada solicitação |
A seguir, é apresentado o esquema para a tabela de registos de pedidos.
Nome da coluna | Tipo | Description |
---|---|---|
client_request_id |
String | ID de solicitação do cliente, geralmente null . |
databricks_request_id |
String | Databricks solicitar ID. |
date |
Date | Data do pedido. |
timestamp_ms |
Longo | Carimbo de data/hora em milissegundos. |
timestamp |
Carimbo de Data/Hora | Carimbo de data/hora do pedido. |
status_code |
Número inteiro | Código de status do ponto de extremidade. |
execution_time_ms |
Longo | Execução total em milissegundos. |
conversation_id |
String | ID da conversação extraída dos registos de pedidos. |
request |
String | A última consulta do usuário da conversa do usuário. Isto é extraído do pedido RAG. |
response |
String | A última resposta ao usuário. Isto é extraído do pedido RAG. |
request_raw |
String | Representação de cadeia de caracteres da solicitação. |
response_raw |
String | Representação de cadeia de caracteres da resposta. |
trace |
String | Representação de cadeia de caracteres do traço extraído do databricks_options Struct da resposta. |
sampling_fraction |
Duplo | Fração de amostragem. |
request_metadata |
Map[String, String] | Um mapa de metadados relacionados ao modelo que serve o ponto de extremidade associado à solicitação. Este mapa contém o nome do ponto de extremidade, o nome do modelo e a versão do modelo usado para o seu ponto de extremidade. |
schema_version |
String | Inteiro para a versão do esquema. |
A seguir está a estrutura da tabela de logs de avaliação.
Nome da coluna | Tipo | Description |
---|---|---|
request_id |
String | Databricks solicitar ID. |
step_id |
String | Derivado da avaliação de recuperação. |
source |
Estrutura | Um campo struct contendo as informações sobre quem criou a avaliação. |
timestamp |
Carimbo de Data/Hora | Carimbo de data/hora do pedido. |
text_assessment |
Estrutura | Um campo struct contendo os dados para qualquer feedback sobre as respostas do agente do aplicativo de avaliação. |
retrieval_assessment |
Estrutura | Um campo struct contendo os dados para qualquer feedback sobre os documentos recuperados para uma resposta. |
Autenticação para recursos dependentes
Os agentes de IA geralmente precisam se autenticar em outros recursos para concluir tarefas. Por exemplo, um agente pode precisar acessar um índice de Pesquisa Vetorial para consultar dados não estruturados.
O seu agente pode usar um dos seguintes métodos para autenticar aos recursos dependentes quando o disponibiliza atrás de um endpoint de serviço de modelo:
- Passagem automática de autenticação: Declare as dependências de recursos do Databricks para o seu agente durante o registo. O Databricks pode provisionar, alternar e gerir automaticamente credenciais de curta duração quando o agente é implantado para aceder a recursos de forma segura. O Databricks recomenda o uso de passagem de autenticação automática sempre que possível.
- Autenticação Manual : Especificar manualmente as credenciais de longa duração durante a implantação do agente. Use a autenticação manual para recursos do Databricks que não suportam passagem de autenticação automática ou para acesso externo à API.
Passagem de autenticação automática
O Model Serving suporta passagem de autenticação automática para os tipos mais comuns de recursos do Databricks usados pelos agentes.
Para habilitar a passagem de autenticação automática, deve-se especificar dependências durante o registo de logs do agente.
Em seguida, quando você atende o agente por trás de um ponto de extremidade, o Databricks executa as seguintes etapas:
Verificação de permissão: Databricks verifica se o criador do ponto final pode aceder a todas as dependências especificadas durante o registo do agente.
Criação e concessões do principal de serviço: Um principal de serviço é criado para a versão do modelo do agente e recebe automaticamente privilégios de leitura aos recursos do agente.
Nota
A entidade de serviço gerada pelo sistema não aparece nas listagens de API nem na interface do utilizador. Se a versão do modelo do agente for removida do ponto de extremidade, a entidade de serviço também será excluída.
de provisionamento e rotação de credenciais: credenciais de curta duração (um token OAuth M2M ) são injetadas no endpoint para o service principal, permitindo que o código do agente aceda aos recursos do Databricks. O Databricks também alterna as credenciais, garantindo que seu agente tenha acesso contínuo e seguro aos recursos dependentes.
Esse comportamento de autenticação é semelhante ao comportamento "Executar como proprietário" para painéis do Databricks - recursos downstream, como tabelas do Unity Catalog, são acessados usando as credenciais de uma entidade de serviço com acesso de privilégios mínimos aos recursos dependentes.
A tabela a seguir lista os recursos do Databricks que oferecem suporte à passagem de autenticação automática e as permissões que o criador do ponto de extremidade deve ter ao implantar o agente.
Nota
Os recursos do Catálogo Unity também exigem USE SCHEMA
no esquema pai e USE CATALOG
no catálogo pai.
Tipo de recurso | Permissão |
---|---|
Armazém SQL | Usar o Endpoint |
Serviço de endpoint do modelo | Pode consultar |
Função do Unity Catalog | EXECUTAR |
Espaço Genie | Pode Executar |
Índice de pesquisa vetorial | Pode usar |
Tabela do Catálogo Unity | SELECT |
Autenticação manual
Você também pode fornecer credenciais manualmente usando variáveis de ambiente baseadas em segredos. A autenticação manual pode ser útil nos seguintes cenários:
- O recurso dependente não suporta passagem de autenticação automática.
- O agente está acessando um recurso externo ou API.
- O agente precisa usar credenciais diferentes daquelas de quem implementa o agente.
Por exemplo, para usar o SDK do Databricks no seu agente para aceder a outros recursos dependentes, pode definir as variáveis de ambiente descritas em Autenticação Unificada do Cliente Databricks.
Obtenha aplicativos implantados
A seguir, mostramos como obter os seus agentes implantados.
from databricks.agents import list_deployments, get_deployments
# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)
deployments = list_deployments()
# Print all the current deployments
deployments
Fornecer feedback sobre um agente implantado (experimental)
Quando você implanta seu agente com agents.deploy()
o , a estrutura do agente também cria e implanta uma versão do modelo de "feedback" dentro do mesmo ponto de extremidade, que você pode consultar para fornecer comentários sobre seu aplicativo de agente. As entradas de feedback surgem como linhas de solicitação na tabela de inferência associada ao ponto de extremidade do serviço do seu agente.
Observe que esse comportamento é experimental: o Databricks pode fornecer uma API de primeira classe para fornecer comentários sobre um agente implantado no futuro, e a funcionalidade futura pode exigir a migração para essa API.
As limitações desta API incluem:
- A API de feedback não tem validação de entrada - ela sempre responde com êxito, mesmo se a entrada inválida for aprovada.
- A API de feedback requer a passagem do Databricks gerado
request_id
da solicitação de ponto de extremidade do agente sobre a qual você deseja fornecer feedback. Para obter odatabricks_request_id
, inclua{"databricks_options": {"return_trace": True}}
em sua solicitação original para o agente que atende o ponto de extremidade. A resposta do ponto de extremidade do agente incluirá odatabricks_request_id
associado à solicitação para que você possa passar esse ID de solicitação de volta para a API de feedback ao fornecer comentários sobre a resposta do agente. - O feedback é coletado usando tabelas de inferência. Consulte as limitações da tabela de inferência, ,.
A seguinte solicitação de exemplo fornece feedback sobre o ponto final do agente chamado "your-agent-endpoint-name" e assume que a variável de ambiente DATABRICKS_TOKEN
está definida como um token da API REST do Databricks.
curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '
{
"dataframe_records": [
{
"source": {
"id": "user@company.com",
"type": "human"
},
"request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
"text_assessments": [
{
"ratings": {
"answer_correct": {
"value": "positive"
},
"accurate": {
"value": "positive"
}
},
"free_text_comment": "The answer used the provided context to talk about Delta Live Tables"
}
],
"retrieval_assessments": [
{
"ratings": {
"groundedness": {
"value": "positive"
}
}
}
]
}
]
}' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations
Você pode passar pares chave-valor adicionais ou diferentes nos text_assessments.ratings
campos e retrieval_assessments.ratings
para fornecer diferentes tipos de feedback. No exemplo, a carga útil de feedback indica que a resposta do agente à solicitação com ID 573d4a61-4adb-41bd-96db-0ec8cebc3744
foi correta, precisa e fundamentada no contexto buscado por uma ferramenta retriever.