部署適用於生成式 AI 應用程式的代理程式
重要
這項功能處於公開預覽狀態。
本文說明如何使用 Agent Framework Python API 中的 函式來部署 AI 代理程式deploy()。
需求
MLflow 2.13.1 或更新版本使用來自
databricks.agents的deploy()API 來部署代理程式。向 Unity 目錄註冊 AI 代理程式。 請參閱將鏈註冊至 Unity 目錄。
安裝
databricks-agentsSDK%pip install databricks-agents dbutils.library.restartPython()
使用 deploy() 部署代理程式
deploy（） 函式會執行下列動作：
- 為代理程式建立可整合至面向使用者應用程式的 CPU 模型服務端點。
- 若要降低閑置端點的成本（代價是提供初始查詢的時間增加），您可以藉由傳遞
scale_to_zero_enabled=True至deploy()，為服務端點啟用調整為零。 請參閱 端點調整預期。 - 推斷資料表會在這些提供端點的模型上啟用。 請參閱監視和偵錯模型的推論表。
- 驗證憑證會自動傳遞至代理程式所需的所有 Databricks 管理資源，如記錄模型時所指定。 Databricks 會建立可存取這些資源的服務主體，並自動將其傳遞至端點。 請參閱相依資源的驗證。
- 如果您有非 Databricks 管理的資源相依性，例如使用 Pinecone，您可以將具有祕密的環境變數傳入
deploy()API。 請參閱設定模型服務端點對資源的存取權。
- 如果您有非 Databricks 管理的資源相依性，例如使用 Pinecone，您可以將具有祕密的環境變數傳入
- 若要降低閑置端點的成本（代價是提供初始查詢的時間增加），您可以藉由傳遞
- 為您的代理程式啟用檢閱應用程式。 檢閱應用程式可讓您的利害關係人與代理程式聊天，並使用檢閱應用程式 UI 提供意見反應。
- 將檢閱應用程式或 REST API 的每個要求記錄至推斷資料表。 記錄的資料包括來自 MLflow 追蹤的查詢要求、回應和中繼追蹤資料。
- 建立意見反應模型，其目錄和結構描述與您嘗試部署的代理程式相同。 此意見反應模型是一種機制，可讓您接受檢閱應用程式的意見反應，並將其記錄至推斷資料表。 此模型會在與已部署的代理程式相同的 CPU 模型中提供。 由於此服務端點已啟用推斷資料表，因此可以將檢閱應用程式的意見反應記錄到推斷資料表。
注意
部署最多需要 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 帳戶小組，為您的端點啟用推斷資料表。
| Table | 範例 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 |
String | 使用者端要求識別碼，通常是 null。 |
databricks_request_id |
String | Databricks 要求 ID。 |
date |
Date | 要求日期。 |
timestamp_ms |
Long | 時間戳記以毫秒為單位。 |
timestamp |
時間戳記 | 要求的時間戳。 |
status_code |
整數 | 端點的狀態代碼。 |
execution_time_ms |
Long | 總執行毫秒數。 |
conversation_id |
String | 從要求記錄擷取的交談識別碼。 |
request |
String | 使用者交談中的最後一個使用者查詢。 這會從 RAG 要求擷取。 |
response |
String | 使用者的最後一個回覆。 這會從 RAG 要求擷取。 |
request_raw |
String | 要求的字串表示法。 |
response_raw |
String | 回應的字串表示法。 |
trace |
String | 從 databricks_options 回應結構擷取之追蹤的字串表示法。 |
sampling_fraction |
雙重 | 取樣分數。 |
request_metadata |
Map[String, String] | 與模型相關的中繼資料對應，提供與要求相關聯的端點。 這個圖包含端點名稱、模型名稱和端點使用的模型版本。 |
schema_version |
String | 結構描述版本的整數。 |
以下是評估記錄資料表的結構描述。
| 資料行名稱 | 類型 | 描述 |
|---|---|---|
request_id |
String | Databricks 要求 ID。 |
step_id |
String | 衍生自擷取評估。 |
source |
結構 | 結構欄位，其中包含建立評量的人員資訊。 |
timestamp |
時間戳記 | 要求的時間戳記。 |
text_assessment |
結構 | 結構欄位，包含來自檢閱應用程式之代理程式回覆的任何意見反應資料。 |
retrieval_assessment |
結構 | 結構欄位，包含針對回覆所擷取之檔的任何意見反應資料。 |
相依資源的許可權需求
部署具有相依資源的模型時，端點的建立者必須具有下列許可權，視資源類型而定：
| 資源類型 | 權限 |
|---|---|
| Sql 倉儲 | 使用端點 |
| 模型服務端點 | 可以查詢 |
| Unity 目錄函式 | 執行 |
| Genie 空間 | 執行 |
| 向量搜尋索引 | ReadVectorIndex |
| Unity 目錄數據表 | 可讀取 |
相依資源的驗證
建立代理程式部署的模型服務端點時，Databricks 會驗證部署的建立者是否有權存取代理程式相依的所有資源。
針對 LangChain 類別代理程式，相依資源會在代理程式建立和記錄期間自動推斷。 這些資源會記錄在記錄之模型工藝品的 resources.yaml 檔案中。 在部署期間，databricks.agents.deploy 會自動建立存取這些推斷的資源相依性所需的 M2M OAuth 權杖。
針對 PyFunc 類別代理程式，您必須在 resources 參數中記錄已部署的代理程式期間手動指定任何資源相依性。 請參閱 指定 PyFunc 或 LangChain 代理程序的資源。
在部署期間，databricks.agents.deploy 會建立可存在 resources 參數中所指定資源的 M2M OAuth 權杖，並將其部署至已部署的代理程式。
自動驗證傳遞
下表列出支援自動驗證傳遞的功能。 自動驗證傳遞會使用部署建立者的認證，針對支援的功能自動進行驗證。
| 功能 | 最低 mlflow 版本 |
|---|---|
| 向量搜尋索引 | 需要 mlflow 2.13.1 或更新版本 |
| 模型服務端點 | 需要 mlflow 2.13.1 或更新版本 |
| SQL 倉儲 | 需要 mlflow 2.16.1 或更新版本 |
| Unity 目錄函式 | 需要 mlflow 2.16.1 或更新版本 |
手動驗證
如果您有不支援自動驗證傳遞的相依資源，或者想要使用部署建立者以外的認證，可以使用秘密型環境變數手動提供認證。 例如，如果您在代理程式中使用 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()部署代理程式時，代理程式架構也會在相同的端點內建立並部署「意見反應」模型版本，您可以查詢以在代理程式應用程式上提供意見反應。 意見反應項目會顯示為與代理程式服務端點相關聯之推斷數據表中的要求數據列。
請注意，此行為是 實驗性的:D atabricks 可能會提供一流的API，以在未來提供已部署代理程式的意見反應，未來功能可能需要移轉至此 API。
此 API 的限制包括：
- 意見反應 API 缺少輸入驗證 - 即使傳遞無效的輸入，它一律會成功回應。
- 意見反應 API 需要傳入您想要提供意見反應的代理程式端點要求 Databricks 產生的
request_idDatabricks。 若要取得databricks_request_id，請在{"databricks_options": {"return_trace": True}}原始要求中包含服務端點的代理程式。 代理程式端點回應接著會包含databricks_request_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
您可以在和 retrieval_assessments.ratings 欄位中傳遞其他或不同的索引鍵/值組text_assessments.ratings，以提供不同類型的意見反應。 在範例中，意見反應承載表示代理程式對標識符 573d4a61-4adb-41bd-96db-0ec8cebc3744 為正確、準確且以擷取器工具所擷取的內容來回應要求。