Implantar um agente para aplicativo de IA generativa
Prévia
Esse recurso está em Pré-lançamento público.
Este artigo mostra como implantar seu agenteAI usando a função deploy()
do Agent Framework Python API .
Requisitos
MLflow 2.13.1 ou superior para implantar agentes utilizando a API
deploy()
dedatabricks.agents
.registrar um agente AI para Unity Catalog. Veja o registro do agente em Unity Catalog.
Deve ser executado a partir de um Databricks Notebook. No momento, não há suporte para o implante de agentes a partir de uma sessão local ou de trabalho.
Instale o SDK do
databricks-agents
.%pip install databricks-agents dbutils.library.restartPython()
Implante um agente com deploy()
A função implantado() faz o seguinte:
Cria endpoint de serviço do modelo de CPU para o seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
Para reduzir o custo do endpoint parado (às custas do aumento do tempo para atender às consultas iniciais), o senhor pode ativar a escala para zero para o seu serviço endpoint passando
scale_to_zero_enabled=True
paradeploy()
. Consulte as expectativas de escalonamento de endpoints.As tabelas de inferência estão ativadas nesses endpoints de modelo de serviço. Consulte Tabelas de inferência para modelos de monitoramento e depuração.
Databricks fornece automaticamente credenciais de entidade de serviço de curta duração para o código do agente em execução no site endpoint. As credenciais têm as permissões mínimas para Databricksacessar -gerenciar recurso conforme definido durante o registro do modelo. Antes de gerar essas credenciais, a Databricks garante que o proprietário do endpoint tenha as permissões adequadas para evitar o aumento de privilégios e o acesso não autorizado. Consulte Autenticação para recurso dependente.
Se o senhor tiver dependências de recurso que não sejam Databricks-gerenciar, por exemplo, usando o Pinecone, poderá passar a variável de ambiente com segredos para o
deploy()
API. Consulte Configurar o acesso ao recurso a partir do endpoint do modelo de atendimento.
Ativa o aplicativo de avaliação para seu agente. O Review App permite que as partes interessadas conversem com o agente e forneçam feedback usando a interface do usuário do Review App.
registra todas as solicitações no Review App ou REST API em uma tabela de inferência. Os registros de dados 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 o senhor está tentando implantar. Esse modelo de feedback é o mecanismo que torna possível aceitar o feedback do aplicativo Review e log para uma tabela de inferência. Esse modelo é servido na mesma CPU servindo modelo endpoint que seu agente implantado. Como este serviço endpoint tem tabelas de inferência ativadas, é possível log feedback do Review App para uma tabela de inferência.
Observação
As implementações podem levar até 15 minutos para serem concluídas. Os payloads de JSON brutos levam de 10 a 30 minutos para chegar e os registros formatados são processados a partir dos payloads brutos a cada hora.
Observação
Atualmente, a função deploy()
só é compatível com o Databricks Notebook.
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 agentes
O deploy()
cria três tabelas de inferência para cada implantação para log solicitações e respostas de e para o agente que atende endpoint. Os usuários podem esperar que os dados estejam na tabela de carga útil dentro de uma hora após a interação com a implantaçã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 útil bruta. O senhor mesmo pode extrair os 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.
Tabela |
Exemplo de nome da tabela do Unity Catalog |
O que há em cada tabela |
---|---|---|
Payload |
|
Cargas de solicitação e resposta JSON brutas |
Logs de solicitação de payload |
|
Solicitação e respostas formatadas, rastreamentos do MLflow |
Logs de avaliação de payload |
|
Feedback formatado, conforme apresentado no aplicativo de avaliação, para cada solicitação |
Veja a seguir o esquema da tabela de logs de solicitação.
Nome da coluna |
Tipo |
Descrição |
---|---|---|
|
String |
ID da solicitação do cliente, geralmente |
|
String |
ID da solicitação do Databricks. |
|
Data |
Data da solicitação. |
|
Long |
Carimbo de data/hora em milissegundos. |
|
Carimbo de data/hora |
Carimbo de data/hora da solicitação. |
|
Integer |
Código de status de endpoint. |
|
Long |
Execução total em milissegundos. |
|
String |
ID da conversa extraído da solicitação logs. |
|
String |
A última consulta do usuário na conversa do usuário. Isso é extraído da solicitação RAG. |
|
String |
A última resposta ao usuário. Isso é extraído da solicitação RAG. |
|
String |
representação de strings da solicitação. |
|
String |
representação em strings da resposta. |
|
String |
representação de strings do traço extraído do site |
|
Double |
Fração de amostragem. |
|
Map[strings, strings] |
Um mapa de metadados relacionados ao modelo de serviço endpoint associado à solicitação. Esse mapa contém o nome endpoint, o nome do modelo e a versão do modelo usados para o seu endpoint. |
|
String |
Número inteiro para a versão do esquema. |
A seguir, o esquema da tabela de logs de avaliação.
Nome da coluna |
Tipo |
Descrição |
---|---|---|
|
String |
ID da solicitação do Databricks. |
|
String |
Derivado da avaliação de recuperação. |
|
struct |
Um campo estruturado que contém as informações sobre quem criou a avaliação. |
|
Carimbo de data/hora |
Carimbo de data/hora da solicitação. |
|
struct |
Um campo de estrutura contendo os dados de qualquer feedback sobre as respostas do agente no aplicativo de avaliação. |
|
struct |
Um campo de estrutura contendo os dados de qualquer feedback sobre os documentos recuperados para uma resposta. |
Autenticação para recurso dependente
AI Os agentes geralmente precisam se autenticar em outro recurso para concluir a tarefa. Por exemplo, um agente pode precisar acessar um índice de pesquisa vetorial para consultar dados não estruturados.
Seu agente pode usar um dos métodos a seguir para se autenticar no recurso dependente quando o senhor o atende por meio de um modelo de atendimento endpoint:
Passagem automática de autenticação: Declare as dependências do recurso Databricks para o seu agente durante o registro. Databricks pode provisionar, girar e gerenciar automaticamente credenciais de curta duração quando seu agente é implantado para acessar recursos com segurança. A Databricks recomenda o uso de passagem automática de autenticação sempre que possível.
Autenticação manual: especifique manualmente credenciais de longa duração durante a implantação do agente. Use a autenticação manual para Databricks recurso que não seja compatível com a passagem automática de autenticação ou para acesso externo a API.
Passagem automática de autenticação
O modelo de serviço oferece suporte à passagem automática de autenticação para os tipos mais comuns de Databricks recurso usados pelos agentes.
Para ativar a passagem automática de autenticação, você deve especificar dependências durante o registro do agente.
Então, quando o senhor serve o agente por trás de um endpoint, o Databricks executa as seguintes etapas:
Verificação de permissão: A Databricks verifica se o criador do endpoint pode acessar todas as dependências especificadas durante o registro em log do agente.
criação e concessões da entidade de serviço: Uma entidade de serviço é criada para a versão do modelo do agente e recebe automaticamente acesso de leitura ao recurso do agente.
Observação
A entidade de serviço gerada pelo sistema não aparece nas listagens da API ou da UI. Se a versão do modelo do agente for removida do endpoint, a entidade de serviço também será excluída.
Provisionamento e rotação de credenciais: Credenciais de curta duração ( tokens M2M OAuth ) para a entidade de serviço são injetadas no site endpoint, permitindo que o código do agente acesse o recurso Databricks. Databricks também alterna as credenciais, garantindo que seu agente tenha acesso contínuo e seguro ao recurso dependente.
Esse comportamento de autenticação é semelhante ao comportamento de "execução como proprietário" dos painéis do site Databricks - recursos downstream, como as tabelas do site Unity Catalog, são acessados usando as credenciais de uma entidade de serviço com acesso de menor privilégio ao recurso dependente.
A tabela a seguir lista o recurso Databricks que suporta a passagem automática de autenticação e as permissões que o criador do endpoint deve ter ao implantar o agente.
Observação
Unity Catalog O recurso também requer USE SCHEMA
no esquema pai e USE CATALOG
no catálogo pai.
Tipo de recurso |
Permissão |
---|---|
SQL Warehouse |
Usar endpoint |
Modelo de ponto de extremidade de serviço |
Pode consultar |
Unity Catalog Função |
EXECUTAR |
Espaço Genie |
Pode executar |
Índice de pesquisa vetorial |
Pode usar |
Unity Catalog Tabela |
SELECIONAR |
Autenticação manual
O senhor também pode fornecer credenciais manualmente usando a variável de ambiente baseada em segredos. A autenticação manual pode ser útil nos seguintes cenários:
O recurso dependente não é compatível com a passagem automática de autenticação.
O agente está acessando um recurso externo ou uma API.
O agente precisa usar credenciais diferentes das do implantador do agente.
Por exemplo, para usar o Databricks SDK em seu agente para acessar outro recurso dependente, o senhor pode definir a variável de ambiente descrita em Databricks autenticação unificada de cliente.
Receba aplicativos implantados
A seguir, mostramos como fazer seus agentes serem 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 o agente é implantado com agents.deploy()
, a estrutura do agente também cria e implanta uma versão do modelo de "feedback" no mesmo endpoint, que pode ser consultado para fornecer feedback sobre o aplicativo do agente. As entradas de feedback aparecem como linhas de solicitação na tabela de inferência associada ao endpoint de atendimento do agente.
Observe que esse comportamento é experimental: A Databricks pode fornecer uma API de primeira classe para fornecer feedback sobre um agente implantado no futuro, e a funcionalidade futura pode exigir a migração para essa API.
As limitações dessa API incluem:
A API de feedback não tem validação de entrada - ela sempre responde com êxito, mesmo se for passada uma entrada inválida.
O feedback API requer a passagem do Databricks-generated
request_id
da solicitação do agente endpoint sobre a qual o senhor deseja fornecer feedback. Para obter odatabricks_request_id
, inclua{"databricks_options": {"return_trace": True}}
em sua solicitação original para o endpoint de atendimento do agente. A resposta do agente endpoint incluirá então odatabricks_request_id
associado à solicitação para que o senhor possa passar essa ID de solicitação de volta para o feedback API ao fornecer feedback sobre a resposta do agente.O feedback é coletado usando tabelas de inferência. Veja as limitações da tabela de inferência.
O exemplo de solicitação a seguir fornece feedback sobre o agente endpoint denominado "your-agent-endpoint-name" e pressupõe que a variável DATABRICKS_TOKEN
de ambiente esteja definida como Databricks REST API tokens.
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
O senhor pode passar par key-value adicionais ou diferentes nos campos text_assessments.ratings
e retrieval_assessments.ratings
para fornecer diferentes tipos de feedback. No exemplo, a carga de feedback indica que a resposta do agente à solicitação com ID 573d4a61-4adb-41bd-96db-0ec8cebc3744
foi correta, precisa e baseada no contexto obtido por uma ferramenta de recuperação.