implantado um agente para o aplicativo generativo AI
Este artigo mostra como implantar seu agenteAI em Mosaic AI Model Serving usando a função deploy()
do Agent Framework Python API .
Os agentes implantados no site Mosaic AI Model Serving oferecem os seguintes benefícios:
- servindo modelo gerenciar autoscale, logging, controle de versão e controle de acesso, permitindo que o senhor se concentre no desenvolvimento de agentes de qualidade.
- Os especialistas no assunto podem usar o Review App para interagir com o agente implantado e fornecer feedback que será incorporado ao monitoramento e às avaliações.
- Você pode monitorar o agente executando uma avaliação do tráfego ao vivo. Embora o tráfego de usuários não inclua a verdade básica, os juízes do LLM (e as métricas personalizadas que o senhor criou) realizam uma avaliação não supervisionada.
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.
-
A implantação de agentes de fora de um notebook Databricks requer
databricks-agents
SDK versão 0.12.0 ou acima. -
Instale o SDK do
databricks-agents
.Python%pip install databricks-agents
dbutils.library.restartPython()
implantado um agente usando 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. -
Permite tabelas de inferência com o AI Gateway no modelo de serviço endpoint. Consulte Monitorar modelos atendidos usando tabelas de inferência habilitadas pelo AI Gateway.
-
Para a resposta de transmissão logs, somente os campos e rastros compatíveis com o ChatCompletion são agregados.
-
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.
- 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
-
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 aplicativo Review 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.
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.
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
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.
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 faz a rotação das 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.
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.
Monitorar agentes implantados
Depois que um agente é implantado no Databricks servindo modelo, o senhor pode usar as tabelas de inferência do AI Gateway para monitorar o agente implantado. As tabelas de inferência contêm detalhes logs de solicitações, respostas, rastreamentos de agentes e feedback de agentes do aplicativo de análise. Essas informações permitem que o senhor depure problemas, monitore o desempenho e crie um golden dataset para avaliação off-line.
Consulte Monitorar agentes implantados com tabelas de inferência.
Obter 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 DLT"
}
],
"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.