部署適用於產生 AI 應用程式的代理程式

本文說明如何使用來自 Agent Framework Python API的 deploy() 函式，將 AI 代理程式 部署至馬賽克 AI 模型服務。

在馬賽克 AI 模型服務上部署代理程式可提供下列優點：

• 模型服務會管理自動調整、記錄、版本控制和訪問控制，讓您專注於開發品質代理程式。
• 主題專家可以使用檢閱應用程式與已部署的代理程序互動，並提供意見反應，以納入您的監視和評估。
• 您可以在即時流量資料上進行評估以監控代理。 雖然使用者流量不會包含真實資料，但 LLM 判斷工具（以及您建立的自定義計量）會執行不受監督的評估。

需求

• 使用 deploy() 的databricks.agents API 部署代理程式時，需使用 MLflow 2.13.1 或更新版本。

• 向 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()。 請參閱設定模型服務端點對資源的存取權。
啟用檢閱應用程式	可讓利害關係人與代理互動並提供回饋。 請參閱 使用審查應用程式對生成式 AI 應用程式 （MLflow 2） 進行人工檢閱。
啟用推斷數據表	藉由記錄要求輸入和回應來監視和偵錯代理程式。 針對 ChatAgent 和 ChatModel 代理程式，AI 閘道會啟用推斷數據表。 針對其他 已被取代的代理程序架構，會使用 標準推斷數據表 。 針對串流回應記錄，只會匯總與 ChatAgent 和 ChatCompletion 相容的欄位和追蹤。
記錄 REST API 要求並檢閱應用程式意見反應	將 API 要求和意見反應記錄至推斷數據表。 建立意見反應模型 ，以接受並記錄來自檢閱應用程式的意見反應。 此模型被部署於與您的代理程式相同的 CPU 型號服務端點。
啟用 Gen AI 的 Lakehouse 監視 （beta）	需要在 Lakehouse Monitoring for Gen AI Beta 中註冊。 部署的代理追蹤會自動啟用基本監控。
使用 MLflow 3 啟用即時追蹤和監視 （beta）	需要在 Lakehouse Monitoring for Gen AI Beta 中註冊，並使用 MLflow 3.0 或更新版本。 除了記錄從已部署的代理程式到推斷數據表以進行長期儲存之外，Databricks 也會將所部署代理程式的追蹤記錄到 MLflow 實驗，以取得即時可見度。 這樣可減少監視和偵錯延遲。 當您透過 agents.deploy()建立新的端點時，會將監視和追蹤設定為從目前作用中的 MLflow 實驗讀取和寫入。 在呼叫 mlflow.set_experiment() 建立端點之前，請先呼叫 agents.deploy() 以設定特定端點的實驗。 端點中的所有代理程式的追蹤（包括透過後續呼叫 agents.deploy() 新增至端點的代理程式）都會被記錄到此實驗中。 監視在此實驗中計算追蹤記錄的品質量度。 根據預設，只會設定基本監視計量。 若要新增 LLM 評委和更多專案，請參閱 設定監視。

注意

部署最多需要 15 分鐘的時間才能完成。 原始 JSON 酬載需要 10 - 30 分鐘才能到達，而格式化的日誌大約每小時從原始酬載處理一次。

自訂部署

若要自訂部署，您可以將其他自變數傳遞至 deploy()。 例如，您可以透過傳遞 scale_to_zero_enabled=True，為閒置端點啟用零化調整功能。 這可降低成本，但會增加提供初始查詢的時間。

如需更多參數，請參閱 Databricks Agents 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 代理程式通常需要向其他資源進行驗證，才能完成工作。 例如，代理程式可能需要存取向量搜尋索引來查詢非結構化數據。

當您在模型服務端點後方提供服務時，您的代理程式可以使用下列其中一種方法向相依資源進行驗證：

1. 自動身份驗證通過：在登錄期間聲明您的代理程式所需的 Databricks 資源依賴性。 當您的代理程式部署以安全地存取資源時，Databricks 可以自動布建、輪替及管理短期認證。 Databricks 建議盡可能使用自動驗證傳遞。
2. 代表使用者驗證：允許使用代理端使用者憑證來存取 Databricks REST API 和資源
3. 手動驗證：在代理程式部署期間手動指定長期認證。 針對不支援自動驗證傳遞或外部 API 存取的 Databricks 資源，使用手動驗證。

自動驗證通過

Model Serving 支援 Databricks 環境中代理使用最常見資源的自動認證傳遞。

若要啟用自動驗證傳遞，您必須在代理程式登入期間 指定依賴項。

然後，當您在端點後方提供代理程式時，Databricks 會執行下列步驟：

1. 許可權驗證： Databricks 會確認端點創建者可以存取在代理記錄期間指定的所有依賴項。

2. 服務主體的建立和授權：會為代理模型版本建立一個服務主體，並自動授予對代理資源的讀取許可權。

   注意

   系統產生的服務主體不會出現在 API 或 UI 清單中。 如果代理程式模型版本已從端點移除，服務主體也會一併刪除。

3. 認證布建和輪替：會將短期認證（M2M OAuth 令牌）注入端點，以允許服務主體的代理代碼存取 Databricks 資源。 Databricks 也會輪替憑證，確保代理程式能夠持續且安全地存取相依資源。

此驗證行為類似於 Databricks 儀錶板的「以擁有者身分執行」行為，使用最低權限存取相依資源的服務主體憑證來存取下游資源，例如 Unity Catalog 表格。

下表列出支援自動驗證傳遞的 Databricks 資源，以及部署代理程式時端點建立者必須具備的許可權。

注意

Unity Catalog 資源在父架構上需要 USE SCHEMA，在父目錄上需要 USE CATALOG。

資源類型	權限
SQL 資料倉儲	使用端點
模型服務端點	可進行查詢
Unity 目錄功能	執行指令
精靈空間	能跑
向量搜尋索引	可以使用
Unity 目錄數據表	SELECT

代理使用者驗證

代理人員身分驗證允許代理程式開發人員使用代理程式終端使用者的憑證來存取敏感的 Databricks 資源。 若要啟用代表使用者存取資源，有兩個步驟：

1. 在代理程式代碼中，請確保用戶端能存取具有啟用代表使用者的驗證的 databricks 資源。 如需詳細資訊，請參閱 使用代理使用者驗證部署代理程式 。
2. 在代理程式登入時，指定終端使用者所需的 REST API 範圍（例如 vectorsearch.vector-search-endpoints）。 當您的代理程式後續部署時，它可以代表使用者存取 Databricks 資源，但只能使用指定的範圍。 如需 API 範圍的詳細資訊，請參閱 代表用戶驗證。

手動驗證

您也可以使用 秘密型環境變數來手動提供認證，。 在下列情況中，手動驗證很有幫助：

• 相依資源不支援自動驗證傳遞。
• 代理程式正在存取外部資源或 API。
• 代理程式需要使用代理程式部署器以外的認證。

例如，若要在代理程式中使用 Databricks SDK 來存取其他相依資源，您可以設定 Databricks 用戶端統一驗證 中所述的環境變數，。

監視已部署的代理程式

將代理程式部署至 Databricks 模型服務之後，您可以使用 AI 閘道推斷數據表來監視已部署的代理程式。 推斷數據表包含來自檢閱應用程式的要求、回應、代理程序追蹤和代理程式意見反應的詳細記錄。 這項資訊可讓您偵錯問題、監視效能，以及建立用於離線評估的黃金數據集。

這很重要

如果您在呼叫 agents.deploy()時，已在開發環境中安裝 MLflow 3，您的端點會即時將 MLflow 追蹤 記錄到呼叫 agents.deploy()時啟動的 MLflow 實驗。 您可以在部署之前呼叫 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 Agents Python API。

提供已部署代理程式的意見反應（實驗性）

當您使用 agents.deploy()部署代理程式時，代理程式架構也會在相同的端點內建立並部署「意見反應」模型版本，您可以查詢以在代理程式應用程式上提供意見反應。 意見反應項目會在與您的代理程式服務端點相關聯的 推斷表中顯示為 的請求行。

請注意，此行為是 實驗性的:D atabricks 可能會提供一流的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 的要求回應是正確且準確，並且基於擷取器工具所獲取的上下文。

其他資源

• 查詢已部署的馬賽克 AI 代理程式
• Mosaic AI 智能代理評估 （MLflow 2）
• 使用審查應用程式對生成式 AI 應用程式進行人為審查（MLflow 2）
• 偵錯已部署的 AI 代理程式