Развертывание агента для создания приложения искусственного интеллекта

В этой статье показано, как развернуть вашего агента ИИ в службе развертывания моделей Mosaic AI с помощью функции deploy() из API Python Agent Framework.

Развертывание агентов в службе модели ИИ Мозаики обеспечивает следующие преимущества:

• Служба моделей управляет автомасштабированием, ведением журнала, управлением версиями и контролем доступа, что позволяет сосредоточиться на разработке агентов качества.
• Эксперты по темам могут использовать приложение для рецензирования для взаимодействия с развернутым агентом и предоставления отзывов, которые будут включены в ваши процессы мониторинга и оценки.
• Вы можете следить за агентом, запустив оценку на живом трафике. Хотя трафик пользователей не будет включать эталонные данные, судьи LLM (и пользовательская метрика, которую вы создали) выполняют несупервизионную оценку.

Требования

• MLflow 2.13.1 и выше для развертывания агентов с использованием deploy() API из databricks.agents.

• Зарегистрируйте агент ИИ в каталоге Unity. См. зарегистрируйте агента в каталоге Unity.

• Для развертывания агентов вне ноутбука Databricks требуется databricks-agents пакет SDK версии 0.12.0 или выше.

• databricks-agents Установите пакет SDK.

  %pip install databricks-agents
  dbutils.library.restartPython()
  

Развертывание агента с помощью deploy()

Функция deploy() выполняет следующие действия:

• Создает конечные точки обслуживания модели процессора для вашего агента, которые можно интегрировать в приложение, ориентированное на пользователей.

  • Чтобы сократить затраты на неактивные конечные точки (за счет увеличения времени для обслуживания начальных запросов), можно включить функцию масштабирования до нуля для конечной точки обслуживания, передав значение scale_to_zero_enabled=True в deploy(). Ознакомьтесь с ожиданиями масштабирования конечных точек.
  • Включает таблицы для вывода с помощью AI Gateway в конечной точке обработки модели. См. статью Мониторинг обслуживаемых моделей с использованием таблиц инференции с поддержкой шлюза ИИ.

  Примечание.

  В журналах потоковых ответов агрегируются только поля и трассировки, совместимые с ChatCompletion.

  • Databricks автоматически предоставляет краткосрочные учетные данные служебной учетной записи для кода агента, выполняющегося в конечной точке. Учетные данные имеют минимальные разрешения для доступа к ресурсам, находящимся под управлением Databricks, определенные при журналировании моделей. Перед созданием этих учетных данных Databricks гарантирует, что владелец конечной точки имеет соответствующие разрешения для предотвращения эскалации привилегий и несанкционированного доступа. См. Проверка подлинности для зависимых ресурсов.
    • Если у вас есть зависимости ресурсов, которые не управляются Databricks, например, когда используется Pinecone, вы можете передать в API deploy() переменные среды с секретными данными. См. раздел "Настройка доступа к ресурсам из конечных точек обслуживания модели".

• Включает приложение для рецензирования для вашего агента. Приложение проверки позволяет заинтересованным лицам общаться с агентом и предоставлять отзывы с помощью пользовательского интерфейса приложения проверки.

• Записывает каждый запрос в приложение проверки или REST API в таблицу вывода. Данные, зарегистрированные в журнале, включают запросы, ответы и промежуточные данные трассировки из MLflow Tracing.

• Создает модель обратной связи с тем же каталогом и схемой, что и агент, который вы пытаетесь развертывать. Эта модель отзывов — это механизм, который позволяет принимать отзывы от приложения проверки и записывать их в таблицу вывода. Эта модель обслуживается на той же конечной точке для обработки ЦП, что и развернутый агент. Так как эта конечная точка предоставления услуг включает инференс-таблицы, можно записать отзывы из Review App в инференс-таблицу.

Примечание.

Развертывание может занять до 15 минут. Необработанные полезные данные JSON приходят через 10 – 30 минут, а форматированные логи формируются из необработанных полезных данных примерно каждый час.

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

Проверка подлинности для зависимых ресурсов

Агенты ИИ часто должны проходить проверку подлинности в других ресурсах для выполнения задач. Например, агенту может потребоваться доступ к индексу векторного поиска для запроса неструктурированных данных.

Ваш агент может использовать один из следующих методов для аутентификации в зависимых ресурсах при обслуживании через конечную точку развёртывания модели:

1. Сквозное автоматическое подтверждение подлинности: объявление зависимостей ресурсов Databricks для вашего агента при логгировании. Databricks может автоматически предоставлять, обновлять и управлять краткосрочными учетными данными при развертывании вашего агента для безопасного доступа к ресурсам. Databricks рекомендует использовать автоматическую сквозную аутентификацию, где это возможно.
2. Ручная аутентификация: Вручную укажите учетные данные с длительным сроком действия во время развертывания агента. Используйте ручную проверку подлинности для ресурсов Databricks, которые не поддерживают автоматическую проверку подлинности, или для внешнего доступа к API.

сквозная автоматическая аутентификация

Сервисы моделей поддерживают автоматическую сквозную аутентификацию для наиболее распространённых типов ресурсов Databricks, используемых агентами.

Чтобы включить автоматическую сквозную аутентификацию, необходимо указать зависимости во время журналирования агента.

Затем, когда вы обслуживаете агента за конечной точкой, Databricks выполняет следующие действия:

1. Проверка разрешений: Databricks проверяет, может ли создатель конечной точки получить доступ ко всем зависимостям, указанным при логировании агентом.

2. Создание и предоставление доступа служебного принципала: служебный принципал создается для версии модели агента и автоматически получает доступ на чтение к ресурсам агента.

   Примечание.

   Системный принципал службы не отображается в списках API или в пользовательских интерфейсах. Если версия модели агента удаляется из конечной точки, субъект-служба также удаляется.

3. предоставление и ротация учетных данных: кратковременные учетные данные (маркер OAuth M2M) для субъекта-службы интегрируются в конечную точку, что позволяет коду агента получать доступ к ресурсам Databricks. Databricks также обновляет учетные данные, гарантируя, что ваш агент имеет постоянный и безопасный доступ к зависимым ресурсам.

Это поведение проверки подлинности аналогично поведению "Запуск от имени владельца" для панелей мониторинга Databricks. К нижестоящим ресурсам, таким как таблицы каталога Unity, обращаются с помощью учетных данных субъекта-службы с минимальными привилегиями доступа к зависимым ресурсам.

В следующей таблице перечислены ресурсы Databricks, поддерживающие автоматическую передачу аутентификации, и разрешения, которые должен иметь создатель конечной точки при развертывании агента.

Примечание.

Ресурсы каталога Unity также требуют наличие USE SCHEMA в родительской схеме и USE CATALOG в родительском каталоге.

Тип ресурса	Разрешение
Хранилище SQL	Используйте конечную точку
Конечная точка обслуживания модели	Может выполнять запрос
Функция каталога Unity	ИСПОЛНЯТЬ
Пространство Genie	Может запускаться
Индекс векторного поиска	Может использовать
Таблица каталога Unity	SELECT

Проверка подлинности вручную

Вы также можете вручную предоставить учетные данные с помощью переменных среды, основывающихся на секретах . Проверка подлинности вручную может оказаться полезной в следующих сценариях:

• Зависимый ресурс не поддерживает автоматическую передачу аутентификации.
• Агент обращается к внешнему ресурсу или API.
• Агент должен использовать учетные данные, отличные от учетных данных развертывающего агента.

Например, чтобы использовать пакет SDK Databricks в агенте для доступа к другим зависимым ресурсам, можно задать переменные среды, описанные в Databricks унифицированная аутентификация клиента.

Мониторинг развернутых агентов

После развертывания агента в Databricks Model Serving можно использовать таблицы инференции шлюза ИИ для мониторинга развернутого агента. Таблицы вывода данных содержат подробные журналы запросов, ответов, трассировок агента и обратную связь агента из приложения Review. Эта информация позволяет отлаживать проблемы, отслеживать производительность и создавать золотой набор данных для автономной оценки.

См. раздел Мониторинг развернутых агентов с таблицами выводов.

Получить развернутые приложения

В следующем примере показано, как получить ваших развернутых агентов.

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

Запрос развернутых агентов

Вы можете использовать клиент развертываний MLflow (рекомендуется) или клиент Databricks OpenAI для взаимодействия с развернутым агентом.

Клиент развертываний MLflow (рекомендуется)

Для возможности запроса вашей конечной точки и, при необходимости, предоставления custom_inputs и запроса трассы MLflow, рекомендуется использовать клиент развертываний MLflow. Методы predict и predict_stream клиента развертываний соответствуют поведению авторированного агента.

from mlflow.deployments import get_deploy_client

client = get_deploy_client()
input_ex = {
    "messages": [{"role": "user", "content": "What does Databricks do?"}],
    "custom_inputs": {"id": 5},
    "databricks_options": {"return_trace": True},
}
endpoint = "<agent endpoint name>"

response = client.predict(endpoint=endpoint, inputs=input_ex)

streaming_response = client.predict_stream(endpoint=endpoint, inputs=input_ex)

Клиент Databricks OpenAI

Для использования только в чате можно также использовать клиент «OpenAI Databricks».

from databricks.sdk import WorkspaceClient

endpoint = "<agent endpoint name>"
msgs = [{"role": "user", "content": "What does Databricks do?"}]

w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()
response = client.chat.completions.create(model=endpoint, messages=msgs)

streaming_response = client.chat.completions.create(
    model=endpoint, messages=msgs, stream=True
)

Оставить отзыв об экспериментальном развернутом агенте

При развертывании вашего агента с agents.deploy() платформа агента также создаёт и развертывает версию модели обратной связи в той же конечной точке, которую можно запросить, чтобы оставить отзыв о вашем приложении агента. Записи обратной связи отображаются в виде строк запроса в таблице вывода, которая связана с конечной точкой обслуживания вашего агента.

Обратите внимание, что это экспериментальное поведение: Databricks может предоставить API первого класса для предоставления отзывов о развернутом агенте в будущем, а для будущих функций может потребоваться миграция в этот API.

К ограничениям этого API относятся:

• API обратной связи не имеет проверки входных данных. Он всегда отвечает успешно, даже если передан недопустимый вход.
• API обратной связи требует передачи сгенерированного Databricks идентификатора запроса к конечной точке агента, для которого вы хотите дать обратную связь. Чтобы получить databricks_request_id, включите {"databricks_options": {"return_trace": True}} в исходный запрос агенту, обслуживающему конечную точку. Затем ответ конечной точки агента будет включать databricks_request_id, связанный с запросом, чтобы вы могли передать этот идентификатор запроса обратно в API для подачи отзывов, когда предоставляете отзыв на ответ агента.
• Отзывы собираются с помощью таблиц вывода. См. ограничения таблицы вывода.

В следующем примере запроса предоставляется обратная связь о точке подключения агента с именем "your-agent-endpoint-name", и предполагается, что переменная окружения DATABRICKS_TOKEN установлена для токена REST API 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 DLT"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

В полях text_assessments.ratings и retrieval_assessments.ratings можно передать дополнительные или различные пары "ключ-значение", чтобы предоставить разные виды отзывов. В этом примере данные обратной связи указывают, что ответ агента на запрос с идентификатором 573d4a61-4adb-41bd-96db-0ec8cebc3744 был правильным, точным и соответствовал контексту, полученному инструментом извлечения.

Дополнительные ресурсы

• Что такое оценка AI-агента Mosaic?
• Используйте приложение Review для проведения человеческих рецензий на приложение генеративного ИИ