생성 AI 애플리케이션용 에이전트를 배포

이 문서에서는 Agent Framework Python APIdeploy() 함수를 사용하여 Mosaic AI 모델에 AI 에이전트 배포하는 방법을 보여 줍니다.

Mosaic AI Model Service에 에이전트를 배포하면 다음과 같은 이점이 제공됩니다.

• Model Serving는 자동 크기 조정, 로깅, 버전 제어 및 액세스 제어를 관리하므로 품질 에이전트 개발에 집중할 수 있습니다.
• 주제 전문가는 검토 앱을 사용하여 배포된 에이전트와 상호 작용하고 모니터링 및 평가에 통합할 수 있는 피드백을 제공할 수 있습니다.
• 라이브 트래픽에 대한 평가를 실행하여 에이전트를 모니터링할 수 있습니다. 사용자 트래픽에는 기본 진리가 포함되지 않지만 LLM 심사위원(및 사용자가 만든 사용자 지정 메트릭)은 감독되지 않은 평가를 수행합니다.

요구 사항

• MLflow 2.13.1 이상에서는 deploy() API를 사용하여 databricks.agents에서 에이전트를 배포할 수 있습니다.

• Unity 카탈로그에 AI 에이전트를 등록합니다. Unity 카탈로그에 에이전트를 등록하는 항목을 참조하세요.

• Databricks Notebook 외부에서 에이전트를 배포하려면 databricks-agents SDK 버전 0.12.0 이상이 필요합니다.

• 엔드포인트 작성자(에이전트를 배포하는 사용자)는 CREATE VOLUME 배포 시 유추 테이블을 저장하기 위해 선택한 Unity 카탈로그 스키마에 대한 권한이 있어야 합니다. 이렇게 하면 스키마에서 관련 평가 및 로깅 테이블을 만들 수 있습니다. 유추 테이블 사용 및 사용 안 함을 참조하세요.

• databricks-agents SDK를 설치하세요.

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

deploy()를 사용하여 에이전트 배포

deploy()를 사용하여 엔드포인트를 제공하는 모델에 에이전트를 배포합니다.

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

함수는 deploy() 기본적으로 다음 작업을 수행합니다.

deploy() 행동	설명
엔드포인트를 제공하는 CPU 모델 만들기	모델 서비스 엔드포인트를 통해 에이전트를 사용자 대면 애플리케이션에서 접근 가능하게 합니다.
일시적인 서비스 주체 자격 증명 제공	Databricks는 모델을 로깅할 때 정의된 Databricks 관리 리소스에 액세스할 수 있는 최소 권한으로 수명이 짧은 자격 증명을 자동으로 제공합니다. Databricks는 권한 상승 및 무단 액세스를 방지하기 위해 자격 증명을 발급하기 전에 엔드포인트 소유자에게 필요한 권한이 있는지 확인합니다. 종속 리소스에 대한 인증을 참조하세요. 에이전트가 Databricks 관리가 아닌 리소스에 종속된 경우 비밀 deploy()이 포함된 환경 변수를 전달할 수 있습니다. 엔드포인트를 제공하는 모델에서 리소스에 대한 액세스 구성을 참조하세요.
검토 앱 사용	관련자가 에이전트와 상호 작용하고 피드백을 제공할 수 있습니다. Gen AI 앱(MLflow 2)을 사람들이 검토할 때 검토 앱을 사용하세요.
유추 테이블 사용	요청 입력 및 응답을 로깅하여 에이전트를 모니터링하고 디버그합니다. ChatAgent 및 ChatModel 에이전트의 경우, 추론 테이블은 AI 게이트웨이를 사용하여 활성화됩니다. 사용되지 않는 다른 에이전트 스키마의 경우 표준 유추 테이블이 사용됩니다. 스트리밍 응답 로그에서는 ChatAgent 및 ChatCompletion과 호환되는 필드와 추적만 집계됩니다.
REST API 요청 기록 및 앱 피드백 검토	API 요청 및 피드백을 유추 테이블에 기록합니다. 검토 앱에서 피드백을 수락하고 기록하는 피드백 모델을 만듭니다. 이 모델은 배포된 에이전트와 엔드포인트를 제공하는 동일한 CPU 모델에서 제공됩니다.
Lakehouse 모니터링을 Gen AI에서 활성화하기(베타)	Gen AI용 Lakehouse 모니터링 베타에 등록해야 합니다. 배포된 에이전트 추적에 기본 모니터링이 자동으로 활성화됩니다.
MLflow 3(베타)를 사용하여 실시간 추적 및 모니터링 사용	Gen AI 베타용 Lakehouse 모니터링에 등록하고 MLflow 3.0 이상을 사용해야 합니다. Databricks는 배포된 에이전트에서 장기 스토리지를 위한 유추 테이블로 추적을 로깅하는 것 외에도 실시간 가시성을 위해 배포된 에이전트에서 MLflow 실험으로 추적을 기록합니다. 이렇게 하면 모니터링 및 디버깅 대기 시간이 줄어듭니다. 새 엔드포인트를 agents.deploy()를 통해 만들면, 모니터링 및 추적이 현재 활성 MLflow 실험에서 읽기 및 쓰기가 구성됩니다. 특정 엔드포인트에 대한 실험을 구성하려면 mlflow.set_experiment()을 호출한 후, agents.deploy()을 호출하여 엔드포인트를 생성하세요. 엔드포인트의 모든 제공된 에이전트(후속 호출 agents.deploy()을 통해 엔드포인트에 추가된 에이전트 포함)의 추적은 이 실험에 기록됩니다. 모니터링은 이 실험의 추적에 대한 품질 메트릭을 계산합니다. 기본적으로 기본 모니터링 메트릭만 구성됩니다. LLM 심사위원 등을 추가하려면 모니터링 설정을 참조하세요.

참고

배포를 완료하는 데 최대 15분이 소요될 수 있습니다. 원시 JSON 페이로드가 도착하는 데 10~30분이 걸리며 형식이 지정된 로그는 약 1시간마다 원시 페이로드에서 처리됩니다.

배포 구성 맞춤화

배포를 사용자 지정하려면 추가 인수를 deploy()전달할 수 있습니다. 예를 들어, 특정 매개변수를 전달하여 비활성 상태의 엔드포인트에 대해 0으로 크기 조정을 활성화할 수 있습니다. 이렇게 하면 비용이 절감되지만 초기 쿼리를 제공하는 시간이 늘어나게 됩니다.

자세한 매개 변수는 Databricks 에이전트 Python API를 참조하세요.

에이전트 배포를 검색하고 삭제하기

기존 에이전트 배포를 검색하거나 관리합니다.

from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

종속 리소스에 대한 인증

AI 에이전트는 작업을 완료하기 위해 다른 리소스에 인증해야 하는 경우가 많습니다. 예를 들어 에이전트는 구조화되지 않은 데이터를 쿼리하기 위해 Vector Search 인덱스에 액세스해야 할 수 있습니다.

에이전트는 다음 방법 중 하나를 사용하여 Model Serving 엔드포인트 뒤에서 서비스를 제공할 때 종속 리소스에 인증할 수 있습니다.

1. 자동 인증 통과: 로깅하는 동안 에이전트에 대한 Databricks 리소스 종속성을 선언합니다. Databricks는 에이전트가 배포되어 리소스에 안전하게 액세스할 때 수명이 짧은 자격 증명을 자동으로 프로비전, 회전 및 관리할 수 있습니다. Databricks는 가능한 경우 자동 인증 통과를 사용하는 것이 좋습니다.
2. 사용자 대신 인증: 에이전트 최종 사용자 자격 증명을 사용하여 Databricks REST API 및 리소스에 액세스할 수 있습니다.
3. 수동 인증: 에이전트 배포 중에 수명이 긴 자격 증명을 수동으로 지정합니다. 자동 인증 통과를 지원하지 않는 Databricks 리소스 또는 외부 API 액세스를 위해 수동 인증을 사용합니다.

자동 인증 통과

Model Serving는 에이전트에서 사용하는 가장 일반적인 유형의 Databricks 리소스에 대한 자동 인증 통과를 지원합니다.

자동 인증 통과를 사용하도록 설정하려면 에이전트 로깅동안 종속성을 지정해야 합니다.

그런 다음, 엔드포인트 뒤에서 에이전트를 제공하는 경우 Databricks는 다음 단계를 수행합니다.

1. 권한 확인: Databricks는 엔드포인트 작성자가 에이전트 로깅 중에 지정된 모든 종속성에 액세스할 수 있음을 확인합니다.

2. 서비스 주체 만들기 및부여: 에이전트 모델 버전에 대한 서비스 주체가 생성되고 에이전트 리소스에 대한 읽기 권한이 자동으로 부여됩니다.

   참고

   시스템 생성 서비스 주체는 API 또는 UI 목록에 표시되지 않습니다. 에이전트 모델 버전이 엔드포인트에서 제거되면 서비스 주체도 삭제됩니다.

3. 자격 증명 프로비전 및 회전: 서비스 주체에 대한 수명이 짧은 자격 증명(M2M OAuth 토큰)이 엔드포인트에 삽입되어 에이전트 코드가 Databricks 리소스에 액세스할 수 있도록 합니다. 또한 Databricks는 자격 증명을 회전하여 에이전트가 종속 리소스에 계속 안전하게 액세스할 수 있도록 합니다.

이 인증 동작은 Databricks 대시보드의 "소유자 권한으로 실행" 동작과 유사합니다. Unity 카탈로그 테이블과 같은 다운스트림 리소스는 종속 리소스에 대한 최소 권한 액세스 권한이 있는 서비스 주체의 자격 증명을 사용하여 액세스합니다.

다음 표에서는 자동 인증 통과를 지원하는 Databricks 리소스와 에이전트를 배포할 때 엔드포인트 작성자가 가져야 하는 사용 권한을 나열합니다.

참고

Unity 카탈로그 리소스에는 부모 스키마에 대한 USE SCHEMA 및 부모 카탈로그의 USE CATALOG이 필요합니다.

리소스 종류	허가
SQL Warehouse	엔드포인트 사용
모델 서비스 접속점	쿼리 수행 가능
Unity 카탈로그 함수	실행하다
지니 공간	달릴 수 있습니다.
벡터 검색 인덱스	사용 가능
Unity 카탈로그 테이블	SELECT

사용자 대신 인증

사용자 대신 인증을 사용하면 에이전트 개발자가 에이전트의 최종 사용자 자격 증명을 사용하여 중요한 Databricks 리소스에 액세스할 수 있습니다. 리소스에 사용자가 대신하여 접근할 수 있도록 설정하려면 다음 두 단계를 수행합니다.

1. 에이전트 코드에서 사용자 대신 인증을 사용하도록 설정된 클라이언트를 사용하여 databricks 리소스에 액세스하고 있는지 확인합니다. 자세한 내용은 사용자 대신 인증을 사용하여 에이전트 배포 를 참조하세요.
2. 에이전트 로깅 시 에이전트에 필요한 최종 사용자 REST API 범위(예 vectorsearch.vector-search-endpoints: )를 지정합니다. 에이전트가 이후에 배포되면 지정된 범위만 사용하여 최종 사용자를 대신하여 Databricks 리소스에 액세스할 수 있습니다. API 범위에 대한 자세한 내용은 사용자 대신 인증을 참조하세요.

수동 인증

비밀 기반 환경 변수를 사용하여 자격 증명을 수동으로 제공할 수도 있습니다. 수동 인증은 다음 시나리오에서 유용할 수 있습니다.

• 종속 리소스는 자동 인증 통과를 지원하지 않습니다.
• 에이전트가 외부 리소스 또는 API에 액세스하고 있습니다.
• 에이전트는 에이전트 배포자 이외의 자격 증명을 사용해야 합니다.

예를 들어 에이전트의 Databricks SDK를 사용하여 다른 종속 리소스에 액세스하려면 Databricks 클라이언트 통합 인증설명된 환경 변수를 설정할 수 있습니다.

에이전트 배포 상태 모니터링

에이전트가 Databricks Model Serving에 배포된 후 AI 게이트웨이 유추 테이블을 사용하여 배포된 에이전트를 모니터링할 수 있습니다. 유추 테이블에는 검토 앱의 요청, 응답, 에이전트 추적 및 에이전트 피드백에 대한 자세한 로그가 포함됩니다. 이 정보를 통해 문제를 디버그하고, 성능을 모니터링하고, 오프라인 평가를 위한 골든 데이터 세트를 만들 수 있습니다.

중요합니다

호출agents.deploy()할 때 MLflow 3이 개발 환경에 설치된 경우 엔드포인트는 호출 시 활성화된 agents.deploy()을 실시간으로 기록합니다. 배포 전에 활성 실험을 변경하도록 호출 mlflow.set_experiment() 할 수 있습니다.

자세한 내용은 MLflow 문서를 참조하세요.

추적을 사용하여 앱 디버그 및 관찰을 참조하세요.

배포된 애플리케이션 가져오기

다음은 배치된 에이전트를 가져오는 방법을 보여줍니다.

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

Databricks 에이전트 Python API를 참조하세요.

배포된 에이전트에 대한 피드백 제공(실험적)

에이전트를 agents.deploy()사용하여 배포하는 경우 에이전트 프레임워크는 동일한 엔드포인트 내에 "피드백" 모델 버전을 만들고 배포하며, 이를 쿼리하여 에이전트 애플리케이션에 피드백을 제공할 수 있습니다. 피드백 항목은 엔드포인트를 제공하는 에이전트와 연결된 유추 테이블 내의 요청 행으로 표시됩니다.

이 동작은 실험적입니다. Databricks는 나중에 배포된 에이전트에 대한 피드백을 제공하기 위한 일류 API를 제공할 수 있으며, 향후 기능을 사용하려면 이 API로 마이그레이션해야 할 수 있습니다.

이 API의 제한 사항은 다음과 같습니다.

• 피드백 API는 입력 유효성 검사가 부족합니다. 잘못된 입력을 전달한 경우에도 항상 성공적으로 응답합니다.
• 피드백 API를 사용하려면 피드백을 제공하려는 에이전트 엔드포인트 요청의 Databricks 생성 request_id 을 전달해야 합니다. databricks_request_id얻으려면 엔드포인트를 제공하는 에이전트에 대한 원래 요청에 {"databricks_options": {"return_trace": True}} 포함합니다. 그러면 에이전트 엔드포인트 응답에 요청과 연결된 databricks_request_id 포함되므로 에이전트 응답에 대한 피드백을 제공할 때 해당 요청 ID를 피드백 API에 다시 전달할 수 있습니다.
• 피드백은 유추 테이블을 사용하여 수집됩니다. 유추 테이블 제한을참조하세요.

다음 예제 요청은 "your-agent-endpoint-name"이라는 에이전트 엔드포인트에 대한 피드백을 제공하고 DATABRICKS_TOKEN 환경 변수가 Databricks REST API 토큰으로 설정된다고 가정합니다.

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 Lakeflow Declarative Pipelines"
                      }
                  ],
                  "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 필드에 추가 또는 다른 키-값 쌍을 전달하여 다양한 유형의 피드백을 제공할 수 있습니다. 이 예제에서 피드백 페이로드는 ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 가 있는 요청에 대한 에이전트의 응답이 정확하고 적절하며 리트리버 도구에서 가져온 맥락에 기반을 두었음을 나타냅니다.

추가 리소스

• Mosaic AI 에이전트를 배포한 후 쿼리하기
• 모자이크 AI 에이전트 평가(MLflow 2)
• Gen AI 앱의 사용자 검토를 위해 검토 앱 사용(MLflow 2)
• 배포된 AI 에이전트 디버그