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

이 문서에서는 에이전트 프레임워크 Python API의 함수를 사용하여 AI 에이전트deploy()하는 방법을 보여 줍니다.

요구 사항

• MLflow 2.13.1 이상에서 deploy()의 databricks.agents API를 사용하여 에이전트를 배포합니다.

• Unity Catalog에 AI 에이전트를 등록합니다. 에이전트를 Unity 카탈로그에 등록하는 방법은 을(를) 참조하십시오.

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

• databricks-agents SDK를 설치합니다.

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

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

deploy() 함수는 다음을 수행합니다.

• 사용자 연결 애플리케이션에 통합할 수 있는 에이전트에 대한 엔드포인트를 제공하는 CPU 모델을 만듭니다.
  • 유휴 엔드포인트에 대한 비용을 줄이려면(초기 쿼리를 제공하는 시간이 늘어나면) 서비스 엔드포인트에 전달 scale_to_zero_enabled=Truedeploy()하여 크기 조정을 0으로 설정할 수 있습니다. 엔드포인트 크기 조정 기대치를 참조 하세요.
  • 이러한 모델 서비스 엔드포인트에서 유추 테이블을 사용할 수 있습니다. 모델 모니터링 및 디버깅을 위한 유추 테이블에 대해 알아봅니다.
  • Databricks는 엔드포인트에서 실행되는 에이전트 코드에 수명이 짧은 서비스 주체 자격 증명을 자동으로 제공합니다. 자격 증명은 모델 로깅동안 정의된 대로, Databricks가 관리하는 리소스에 액세스하기 위한 최소 권한을 가지고 있습니다. 이러한 자격 증명을 생성하기 전에 Databricks는 엔드포인트 소유자가 권한 상승 및 무단 액세스를 방지하기 위한 적절한 권한을 갖도록 합니다. 종속 리소스에 대한 인증을 참조하세요.
    • 예를 들어 Pinecone을 사용하여 Databricks에서 관리되지 않는 리소스 종속성이 있는 경우 비밀이 있는 환경 변수를 deploy() API에 전달할 수 있습니다. 엔드포인트를 제공하는 모델에서 리소스에 대한 액세스 구성을 참조하세요.
• 에이전트에 대해 검토 앱을 사용하도록 설정합니다. 검토 앱을 사용하면 관련자가 에이전트와 채팅하고 앱 검토 UI를 사용하여 피드백을 제공할 수 있습니다.
• 검토 앱 또는 REST API에 대한 모든 요청을 유추 테이블에 기록합니다. 기록된 데이터에는 쿼리 요청, 응답 및 MLflow 추적의 중간 추적 데이터가 포함됩니다.
• 배포하려는 에이전트와 동일한 카탈로그 및 스키마를 사용하여 피드백 모델을 만듭니다. 이 피드백 모델은 검토 앱의 피드백을 수락하고 유추 테이블에 기록할 수 있도록 하는 메커니즘입니다. 이 모델은 배포된 에이전트와 엔드포인트를 제공하는 동일한 CPU 모델에서 제공됩니다. 이 서비스 엔드포인트에는 유추 테이블이 활성화되어 있으므로 검토 앱의 피드백을 유추 테이블로 기록할 수 있습니다.

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()는 각 배포에 대한 세 개의 유추 테이블을 만들어 엔드포인트를 제공하는 에이전트에 대한 요청 및 응답을 기록합니다. 사용자는 배포와 상호 작용한 후 1시간 이내에 페이로드 테이블에 데이터가 표시될 것으로 예상할 수 있습니다.

페이로드 요청 로그 및 평가 로그를 채우는 데 시간이 오래 걸릴 수 있지만 궁극적으로 원시 페이로드 테이블에서 파생됩니다. 페이로드 테이블에서 직접 요청 및 평가 로그를 추출할 수 있습니다. 페이로드 테이블에 대한 삭제 및 업데이트는 페이로드 요청 로그 또는 페이로드 평가 로그에 반영되지 않습니다.

다음은 요청 로그 테이블의 스키마입니다.

다음은 평가 로그 테이블에 대한 스키마입니다.

종속 리소스에 대한 인증

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

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

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

자동 인증 통과

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

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

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

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

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

   참고 항목

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

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

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

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

수동 인증

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

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

예를 들어 에이전트의 Databricks SDK를 사용하여 다른 종속 리소스에 액세스하려면 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를 사용하려면 피드백을 제공하려는 에이전트 엔드포인트 요청의 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 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 전달하여 다양한 유형의 피드백을 제공할 수 있습니다. 이 예제에서 피드백 페이로드는 ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 가 있는 요청에 대한 에이전트의 응답이 정확하고 정확하며 리트리버 도구에서 가져온 컨텍스트에서 접지되었음을 나타냅니다.

추가 리소스

• Mosaic AI 에이전트 평가란?
• 에이전트 애플리케이션의 품질에 대한 피드백 받기