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

Статья
12/19/2024

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии.

В этой статье показано, как развернуть агент ИИ с помощью функции из deploy()API Python Agent Framework.

Требования

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=Truedeploy()нее. Ознакомьтесь с ожиданиями масштабирования конечных точек.
- Таблицы вывода включены в этих конечных точках службы моделей. См . таблицы вывода для мониторинга и отладки моделей.
- Databricks автоматически предоставляет краткосрочные учетные данные служебной учетной записи для кода агента, выполняющегося в конечной точке. Учетные данные имеют минимальные разрешения для доступа к ресурсам Databricks, управляемым , как это определено при ведении журнала моделей. Перед созданием этих учетных данных Databricks гарантирует, что владелец конечной точки имеет соответствующие разрешения для предотвращения эскалации привилегий и несанкционированного доступа. См . сведения о проверке подлинности для зависимых ресурсов.
  - Если у вас есть зависимости ресурсов, которые не управляются Databricks, например, когда используется Pinecone, вы можете передать в API deploy() переменные среды с секретными данными. См. раздел "Настройка доступа к ресурсам из конечных точек обслуживания модели".
Включает приложение проверки для агента. Приложение проверки позволяет заинтересованным лицам общаться с агентом и предоставлять отзывы с помощью пользовательского интерфейса приложения проверки.
Записывает каждый запрос в приложение проверки или REST API в таблицу вывода. Данные, зарегистрированные в журнале, включают запросы, ответы и промежуточные данные трассировки из трассировки MLflow.
Создает модель обратной связи с тем же каталогом и схемой, что и агент, который вы пытаетесь развернуть. Эта модель отзывов — это механизм, который позволяет принимать отзывы от приложения проверки и записывать их в таблицу вывода. Эта модель обслуживается в той же модели ЦП, что и развернутый агент. Так как эта конечная точка обслуживания включает таблицы вывода, можно записать отзывы из приложения проверки в таблицу вывода.

Примечание.

Развертывание может занять до 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

Таблицы вывода с расширенными агентами

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

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

Примечание.

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

Таблица	Пример имени таблицы каталога Unity	Что такое в каждой таблице
Полезная нагрузка	`{catalog_name}.{schema_name}.{model_name}_payload`	Полезные данные необработанных запросов и ответов JSON
Журналы запросов полезных данных	`{catalog_name}.{schema_name}.{model_name}_payload_request_logs`	Форматированные запросы и ответы, трассировки MLflow
Журналы оценки полезных данных	`{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs`	Отформатированный отзыв, как указано в приложении проверки, для каждого запроса

Ниже показана схема таблицы журналов запросов.

Имя столбца	Тип	Описание:
`client_request_id`	Строка	Как правило `null`, идентификатор запроса клиента.
`databricks_request_id`	Строка	Идентификатор запроса Databricks.
`date`	Дата	Дата запроса.
`timestamp_ms`	Long	Метка времени в миллисекундах.
`timestamp`	Метка времени	Метка времени запроса.
`status_code`	Целое	Код состояния конечной точки.
`execution_time_ms`	Long	Общее число миллисекундах выполнения.
`conversation_id`	Строка	Идентификатор беседы, извлеченный из журналов запросов.
`request`	Строка	Последний запрос пользователя из беседы пользователя. Это извлекается из запроса RAG.
`response`	Строка	Последний ответ пользователю. Это извлекается из запроса RAG.
`request_raw`	Строка	Строковое представление запроса.
`response_raw`	Строка	Строковое представление ответа.
`trace`	Строка	Строковое представление трассировки, извлеченное из `databricks_options` структуры ответа.
`sampling_fraction`	Двойной	Дробь выборки.
`request_metadata`	Map[String, String]	Карта метаданных, связанных с конечной точкой обслуживания модели, связанной с запросом. Эта карта содержит имя конечной точки, имя модели и версию модели, используемую для конечной точки.
`schema_version`	Строка	Целое число для версии схемы.

Ниже приведена схема для таблицы журналов оценки.

Имя столбца	Тип	Описание:
`request_id`	Строка	Идентификатор запроса Databricks.
`step_id`	Строка	Производный от оценки извлечения.
`source`	Структура	Поле структуры, содержащее сведения о том, кто создал оценку.
`timestamp`	Метка времени	Метка времени запроса.
`text_assessment`	Структура	Поле структуры, содержащее данные для любых отзывов об ответах агента из приложения проверки.
`retrieval_assessment`	Структура	Поле структуры, содержащее данные для любых отзывов о документах, полученных для ответа.

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

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

Агент может использовать один из следующих методов для проверки подлинности в зависимых ресурсах при его обслуживании за конечной точкой обслуживания модели:

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

Сквозное руководство по автоматической проверке подлинности

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

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

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

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

Примечание.

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

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

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

Примечание.

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

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

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

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

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

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

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

Ниже показано, как получить развернутые агенты.

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

Предоставление отзывов о развернутом агенте (экспериментальном)

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

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

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

API обратной связи не имеет проверки входных данных. Он всегда отвечает успешно, даже если передан недопустимый вход.
API обратной связи требует передачи данных, созданного request_id 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 Delta Live Tables"
                      }
                  ],
                  "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 был правильным, точным и приземлен в контексте, полученном средством извлечения.

Поделиться через

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

Требования

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

Таблицы вывода с расширенными агентами

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

Сквозное руководство по автоматической проверке подлинности

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

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

Предоставление отзывов о развернутом агенте (экспериментальном)

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

Обратная связь

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

Поделиться через

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

Требования

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

Таблицы вывода с расширенными агентами

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

Сквозное руководство по автоматической проверке подлинности

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

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

Предоставление отзывов о развернутом агенте (экспериментальном)

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

Обратная связь

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

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