OpenAPI 工具可讓 AI 教練根據對話情境，動態從遠端 API 擷取資料。
事前準備
如果現有 API 發生問題，請採用下列彈性做法：
- 建立 Cloud Run 函式，做為現有 API 的包裝函式。Cloud Run 函式會填入其他必要參數，並對 API 回應執行後續處理。
- 建立 OpenAPI 工具，呼叫 Cloud Run 函式。
Datastore API 可能需要額外的輸入參數 (例如設定搜尋結果模式)，但 Cloud Run 函式只需要一個參數 (查詢)，AI 輔導員可以從對話內容中擷取該參數。在回應處理方面，Cloud Run 函式只會傳回最符合的結果，而不是所有結果。
請按照下列步驟存取 Datastore。
步驟 1：建立 Datastore 和搜尋應用程式
執行下列指令來擷取分塊。
gcurl -sX GET \
"https://discoveryengine.googleapis.com/v1alpha/projects/${project_id}/locations/global/collections/default_collection/dataStores/${data_store_id}/documentProcessingConfig"
以下範例顯示已啟用分塊。
{
"name": "projects/${project_id}/locations/global/collections/default_collection/dataStores/${data_store_id}/documentProcessingConfig",
"chunkingConfig": {
"layoutBasedChunkingConfig": {
"chunkSize": 500,
"includeAncestorHeadings": true
}
},
"defaultParsingConfig": {
"digitalParsingConfig": {}
}
}
執行下列指令，擷取解決方案類型和搜尋層級。
gcurl -X GET \
"https://discoveryengine.googleapis.com/v1alpha/projects/${project_id}/locations/global/collections/default_collection/engines/${data_store_id}"
以下範例顯示解決方案類型和搜尋層級已通過驗證。
{
"name": "projects/${project_id}/locations/global/collections/default_collection/engines/${data_store_id}",
"displayName": "iphone_",
"dataStoreIds": [
"${data_store_id}"
],
"solutionType": "SOLUTION_TYPE_SEARCH",
"searchEngineConfig": {
"searchTier": "SEARCH_TIER_ENTERPRISE"
},
"commonConfig": {
"companyName": "Google"
},
"industryVertical": "GENERIC"
}
步驟 2：建立 Cloud Run 函式來呼叫 Datastore
如要進行驗證，請將 Cloud Run 函式設為需要身分識別權杖。Cloud Run 函式可將複雜的 API 包裝成基本 API。這些動作包括：
- 在要求中填入其他欄位。
- 呼叫 Datastore API 執行搜尋。
- 處理 API 回應並傳回最相關的結果。
建立 Cloud Run 函式後，請建立 OpenAPI 工具來叫用 Cloud Run 函式。
在下列範例中，Cloud Run functions 會轉換 Datastore API，執行搜尋並提供搜尋結果清單。
import os
import requests
import google.auth
import google.auth.transport.requests
import functions_framework
@functions_framework.http
def call_vertex_search(request):
"""
HTTP Cloud Function to invoke a Vertex AI Search endpoint.
"""
# --- Configuration - Tailor to your Vertex AI Search specifics ---
project_id = ${project_id}
engine_id = "${data_store_id}"
# Establish the Vertex AI Search endpoint URL
endpoint = f"https://discoveryengine.googleapis.com/v1alpha/projects/${project_id}/locations/global/collections/default_collection/engines/{engine_id}/servingConfigs/default_chat:search"
# --- Acquire Authentication Token ---
try:
credentials, project = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)
token = credentials.token
except Exception as e:
print(f"Authentication token retrieval error: {e}")
return f"Authentication token retrieval error: {e}", 500
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
# --- Formulate Search Query ---
# Extract the query from the request; otherwise, employ a default.
request_json = request.get_json(silent=True)
query = "what is the price of iphone 13?" # Default query
if request_json and 'query' in request_json:
query = request_json['query']
payload = {
"query": query,
"page_size": 5,
"content_search_spec": {
"search_result_mode": "CHUNKS"
}
# Additional search parameters, such as filters or boost_spec, can be appended here.
# "filter": "some_attribute:ANY(\"value\")",
}
# --- Execute Vertex AI Search API Call ---
try:
response = requests.post(endpoint, headers=headers, json=payload)
response.raise_for_status() # Trigger an exception for unfavorable status codes.
search_results = response.json()
print(f"Search results: {search_results}")
extracted_data = search_results["results"][0]["chunk"]["content"]
if extracted_data is not None:
print(f"Extracted data: {extracted_data}")
return {"content": extracted_data}, 200
else:
print("Failed to extract search results from the response.")
return "Failed to extract search results from the response", 404
except requests.exceptions.RequestException as e:
print(f"Vertex AI Search invocation error: {e}")
if e.response is not None:
print(f"Error details: {e.response.text}")
return f"Vertex AI Search invocation error: {e.response.text}", e.response.status_code
return f"Vertex AI Search invocation error: {e}", 500
except Exception as e:
print(f"An unanticipated error transpired: {e}")
return f"An unanticipated error transpired: {e}", 500
使用 Shell 測試 Cloud Run functions。如以下範例所示，試著傳送「iphone 13 的價格是多少」這類查詢。
export CLOUDSDK_CORE_PROJECT=${project_id}
curl -H "Authorization: Bearer "$(gcloud auth print-identity-token) -H "X-Goog-User-Project: ${CLOUDSDK_CORE_PROJECT}" -H "Content-Type: application/json; charset=utf-8" -X GET "https://${CLOUD_FUNCTION_ENDPOINT}/?query=what%20is%20the%20price%20of%20iphone%2013"
您應該會收到類似以下的回覆：
{"content":"Table of contents\niPhone price history iPhone 4S (2011)\niPhone 4S original starting MSRP: $199\nInflation-adjusted iPhone 4S price: $280\niPhone 5 (2012)\niPhone 5 Original starting MSRP: $199\nInflation-adjusted iPhone 5 price: $276\niPhone 5S/5C (2013) iPhone 5S original starting MSRP: $199\niPhone 5C original starting MSRP: $99\nInflation-adjusted iPhone 5S price: $270\nInflation-adjusted iPhone 5C price: $134\niPhone 6/6 Plus (2014) Table of contents\niPhone price history iPhone 6 original starting MSRP: $199\niPhone 6 Plus original starting MSRP: $299\nInflation-adjusted iPhone 6 price: $266\nInflation-adjusted iPhone 6 Plus price: $398\niPhone 6S/6S Plus (2015)\niPhone 6S original starting MSRP: $199\niPhone 6S Plus original starting MSRP: $299\nInflation-adjusted iPhone 6S price: $265\nInflation-adjusted iPhone 6S Plus price: $397\niPhone 7/7 Plus (2016) Table of contents\niPhone price history iPhone 7 original starting MSRP: $649\niPhone 7 Plus original starting MSRP: $769\nInflation-adjusted iPhone 7 price: $854\nInflation-adjusted iPhone 7 Plus price: $1,011\niPhone 8/8 Plus (2017)\niPhone 8 original starting MSRP: $699\niPhone 8 Plus original starting MSRP: $799\nInflation-adjusted iPhone 8 price: $900\nInflation-adjusted iPhone 8 Plus price: $1,029\niPhone X (2017)\niPhone X original starting MSRP: $999\nInflation-adjusted iPhone X Plus price: $1,287\niPhone XR (2018)\niPhone XR original starting MSRP: $749\nInflation-adjusted iPhone XR Plus price: $942\niPhone XS/S Max (2018) Table of contents\niPhone price history iPhone XS original starting MSRP: $999\niPhone XS Max original starting MSRP: $1,099\nInflation-adjusted iPhone XS price: $1,254\nInflation-adjusted iPhone XS Plus price: $1,380\niPhone 11/Pro/Pro Max (2019)\niPhone 11 original starting MSRP: $699\niPhone 11 Pro original starting MSRP: $999\niPhone 11 Pro Max original starting MSRP: $1099\nInflation-adjusted iPhone 11 price: $863\nInflation-adjusted iPhone 11 Pro price: $1,232\nInflation-adjusted iPhone 11 Pro Max price: $1,355\niPhone 12/Mini/Pro/Pro Max (2020)\niPhone 12 original starting MSRP: $799 Table of contents\niPhone price history Login iPhone 12 Mini original starting MSRP: $699\niPhone 12 Pro original starting MSRP: $999\niPhone 12 Pro Max original starting MSRP: $1099\nInflation-adjusted iPhone 12 price: $976\nInflation-adjusted iPhone 12 Mini price: $853\nInflation-adjusted iPhone 12 Pro price: $1,218\nInflation-adjusted iPhone 12 Pro Max price: $1,340 iPhone 13/Mini/Pro/Pro Max (2021)\niPhone 13 original starting MSRP: $799\niPhone 13 Mini original starting MSRP: $699\niPhone 13 Pro original starting MSRP: $999\niPhone 13 Pro Max original starting MSRP: $1099\nInflation-adjusted iPhone 13 price: $931\nInflation-adjusted iPhone 13 Mini price: $814\nInflation-adjusted iPhone 13 Pro price: $1,163\nInflation-adjusted iPhone 13 Pro Max price: $1,279\niPhone 14/Plus/Pro/Pro Max (2022) Table of contents\niPhone price history Robert Triggs / Android Authority"}
步驟 3：建立 OpenAPI 工具
按照「OpenAPI 和 Integration Connectors 工具」中的步驟，建立 OpenAPI 工具。
以下範例說明 OpenAPI 工具如何與 Cloud Run 函式提供的新 API 互動。
openapi: 3.0.0
info:
title: iphone_price_tool
description: An API to search document about iPhone prices.
version: 1.0.0
servers:
- url: https://${CLOUD_FUNCTION_ENDPOINT}
paths:
/:
get:
summary: Search information about iphone prices
operationId: search
parameters:
- in: query
name: query
schema:
type: string
required: true
description: The user's question about iphone price
responses:
'200':
description: Retrieved information about iphone price
content:
application/json:
schema:
type: object
properties:
content:
type: string
description: Information about iphone price
'400':
description: Bad request, query parameter is missing.
content:
text/plain:
schema:
type: string
example: "Please provide a 'query' as a URL parameter for POST requests (e.g., ?query=your_question)."
'500':
description: Internal server error.
content:
text/plain:
schema:
type: string
example: "Error querying: An unexpected error occurred."
步驟 4：建立產生器
按照「OpenAPI 工具」中的步驟建立 AI 教練生成器。使用 AI 教練生成器內容建構 LLM 提示。