在 AlloyDB for PostgreSQL 中,使用 AI 函式執行查詢時,可透過 AI 函式智慧批次處理功能,達到最佳效能。這項功能提供與陣列型函式相同或更佳的效能,而且您不必將查詢重寫為複雜的陣列結構。如要進一步瞭解 AI 函式,請參閱「AI 函式總覽」。
在標準 PostgreSQL 中,逐列評估 AI 函式會導致每個資料列產生網路延遲。AlloyDB 具備智慧批次處理功能,可自動批次處理符合條件的 AI 作業,並卸載這些作業以進行非同步評估,讓您編寫標準且易於閱讀的 SQL 查詢。標準關聯式篩選器會在 AI 函式之前評估,確保最佳效能和模型用量。
支援的 AI 函式
AlloyDB 智慧批次處理支援下列 AI 函式,這些函式可在 ai 和 google_ml 結構定義中使用:
| 函式 | 說明 | 擴充功能版本 |
|---|---|---|
ai.if(prompt text, ...)/google_ml.if(...) |
評估自然語言布林提示,並傳回 true 或 false。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
全部 |
ai.rank(prompt text, ...)/google_ml.rank(...) |
計算數值關聯性分數 (float),指出輸入內容與指定條件的相符程度。支援 WHERE 篩選器、ORDER BY、SELECT 和 JOIN 子句。 |
全部 |
ai.generate(prompt text, ...)/google_ml.generate(...) |
使用基礎模型生成自然語言回覆或結構化文字。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
全部 |
ai.analyze_sentiment(input text, ...)/google_ml.analyze_sentiment(...) |
分析輸入文字的情緒,並傳回 'positive'、'negative' 或 'neutral'。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
1.6.3 |
ai.summarize(input text, ...)/google_ml.summarize(...) |
摘要輸入文字。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
1.6.4 |
ai.extract(input text, output_schema text, ...)/google_ml.extract(...) (預先發布版;必須設定 google_ml_integration.enable_preview_ai_functions=on) |
從文字中擷取結構化實體或鍵/值屬性。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
1.6.1 |
ai.classify(input text, categories text[][], ...)/google_ml.classify(...) (預先發布版;必須設定 google_ml_integration.enable_preview_ai_functions=on) |
將文字分類至指定的類別標籤。支援 SELECT 投影、WHERE 篩選器和 JOIN 子句。 |
1.6.1 |
如要進一步瞭解 AI 函式的語法和參數,請參閱「模型端點管理參考資料」。
支援的子句
AI 函式加速功能適用於主要 SQL 子句,無論是單獨使用或組合使用皆可:
WHERE子句:評估選擇性非 AI 關聯式述詞後,使用布林 AI 評估 (ai.if) 篩選資料列。ORDER BY子句:在執行排序或限制作業前,批次計算 AI 關聯性分數 (ai.rank)。SELECT投影:批次處理結果列中的純量 AI 函式 (ai.if、ai.rank、ai.generate、ai.analyze_sentiment、ai.summarize、ai.extract和ai.classify)。JOIN ... ON條件:使用智慧批次處理,評估INNER JOIN作業中的跨資料表 AI 條件。- DML 陳述式:加速
UPDATE、DELETE和INSERT ... SELECT作業 (例如INSERT INTO ... SELECT ai.generate(...)和UPDATE ... SET col = ai.generate(...)) 中WHERE述詞、目標清單和SET運算式的 AI 函式。
支援的引數運算式
提示引數支援標準 SQL 運算式,包括:
- 資料欄參照,例如
r.review - 與資料欄參照串連的字串常值,例如
'Is this a positive review? Review: ' || r.review - 串連多個資料欄,例如
r.name || ' ' || r.review - 純量 SQL 運算式和函式,例如
COALESCE(r.review, '')、LOWER(r.comments)、SUBSTRING(description FROM 1 FOR 500)和CASE陳述式
事前準備
如要在 AlloyDB 中使用 AI 函式的智慧批次處理功能,請確認符合下列必要條件:
- PostgreSQL 版本:使用 PostgreSQL 17 以上版本。
- 與 Gemini Enterprise Agent Platform 整合:完成「與 Gemini Enterprise Agent Platform 整合」中的步驟。
- 區域可用性:智慧批次處理功能適用於支援預設模型 (
gemini-3.5-flash-lite) 或使用google_ml_integration.default_llm_model設定模型的區域。詳情請參閱「支援的地區」。
啟用 AI 函式的智慧批次處理功能
在 PostgreSQL 18 以上版本中,AI 函式的智慧批次處理功能預設為啟用。在 PostgreSQL 17 中,這項功能預設為停用,必須明確啟用。您可以透過執行個體層級的資料庫旗標,全域設定其行為,或使用 SQL SET 指令,為每個工作階段設定其行為。
設定參數
| 參數名稱 | 類型 | 預設 | 範圍 | 說明 |
|---|---|---|---|---|
google_ml_integration.enable_ai_function_acceleration |
布林值 | PostgreSQL 18:on PostgreSQL 17: off |
工作階段、使用者或執行個體 | 控管查詢規劃器和執行器是否會卸載符合條件的 AI 作業,以便進行智慧批次處理。如果設為 off,查詢會使用標準 PostgreSQL 逐列執行。 |
其他設定:
- 預先發布版函式:如要為預先發布版中的 AI 函式 (例如
ai.extract和ai.classify) 啟用智慧批次處理功能,請將google_ml_integration.enable_preview_ai_functions設為on。 - 模型選取:如要指定其他模型,而非預設的
gemini-3.5-flash-lite,請將google_ml_integration.default_llm_model設為目標模型 ID,或在 AI 函式中傳遞model_id參數。
在執行個體層級設定
如要在 AlloyDB 叢集中的執行個體層級設定資料庫旗標,請使用 gcloud alloydb instances update 指令:
gcloud alloydb instances update INSTANCE_ID \
--database-flags google_ml_integration.enable_ai_function_acceleration=on \
--region=REGION_ID \
--cluster=CLUSTER_ID \
--project=PROJECT_ID更改下列內容:
INSTANCE_ID:要更新的執行個體 ID。REGION_ID:叢集所在區域的 ID。詳情請參閱「支援的區域」。CLUSTER_ID:叢集 ID。PROJECT_ID:專案 ID。
詳情請參閱「設定資料庫旗標」。
在工作階段層級設定
如要調整或切換工作階段的智慧批次處理參數,請使用 SET 指令:
-- Disable smart batching for the current session (runs standard row-by-row execution)
SET google_ml_integration.enable_ai_function_acceleration = off;
-- Re-enable smart batching
SET google_ml_integration.enable_ai_function_acceleration = on;
-- Enable preview functions (ai.extract, ai.classify)
SET google_ml_integration.enable_preview_ai_functions = on;
驗證 AI 函式的智慧批次處理功能
如要確認 AI 函式的智慧批次處理功能是否已啟用,可以使用 EXPLAIN 陳述式分析查詢。
啟用智慧批次處理功能後,執行計畫會包含 Custom Scan (AIFunctionApply) 或 Parallel Custom Scan (AIFunctionApply) 節點。如果出現這個節點,表示系統會從標準逐列執行作業中,擷取符合條件的 AI 函式呼叫,並以高處理量非同步批次執行。如果沒有這個節點,系統會使用標準 PostgreSQL 逐列評估執行查詢。
驗證 WHERE 子句中的 AI 篩選功能
在 WHERE 子句中,搭配標準關聯式 SQL 述詞使用 AI 布林值函式 (例如 ai.if) 時,AlloyDB 會先使用索引掃描或資料表掃描,評估選擇性關聯式篩選器。接著,AlloyDB 只會加速 AI 評估的候選資料列。例如:
EXPLAIN (COSTS OFF)
SELECT r.name, r.review
FROM restaurant_reviews r
WHERE ai.if('Is the following a positive review? Review: ' || r.review)
AND r.city = 'Los Angeles';
使用 EXPLAIN 陳述式分析查詢時,查詢計畫會顯示 Custom Scan (AIFunctionApply) 節點:
QUERY PLAN
----------------------------------------------------------------------------------------
Custom Scan (AIFunctionApply)
Filter: ai.if(('Is the following a positive review? Review: '::text || review), NULL::character varying)
-> Index Scan using idx_restaurant_reviews_city on restaurant_reviews r
Index Cond: ((city)::text = 'Los Angeles'::text)
關聯篩選器 (city = 'Los Angeles') 會先評估索引,只有相符的資料列會批次傳送至模型進行 ai.if 評估。
透過平行查詢執行作業驗證 AI 投影
SELECT 目標清單中的 AI 評分和生成功能會自動加速。查詢掃描大型資料表時,智慧加速功能會與 PostgreSQL 平行查詢整合,將批次評估作業分配給平行背景 worker:
EXPLAIN (COSTS OFF)
SELECT ai.generate('Summarize the customer sentiment for: ' || r.review) AS review_summary
FROM restaurant_reviews r
WHERE ai.if('Does this review mention food safety concerns? ' || r.review);
查詢計畫輸出內容範例:
QUERY PLAN
------------------------------------------------------------------------------------------------------
Gather
Workers Planned: 4
-> Custom Scan (AIFunctionApply)
-> Parallel Custom Scan (AIFunctionApply)
Filter: ai.if(('Does this review mention food safety concerns? '::text || r.review), NULL::character varying)
-> Parallel Seq Scan on restaurant_reviews r
(6 rows)
備用行為
智慧批次處理提供安全的備用語意。如果查詢包含無法安全加速的建構或模式,查詢不會失敗,而是使用標準 PostgreSQL 逐列執行查詢。
使用 DEBUG2 診斷備用廣告
如要查看查詢使用標準執行作業而非智慧批次處理的原因,請將 client_min_messages 設為 DEBUG2,並執行 EXPLAIN:
SET client_min_messages TO DEBUG2;
EXPLAIN SELECT ...;
RESET client_min_messages;
檢查輸出內容,找出前置字串為 AI function acceleration is not applied 的診斷訊息。
不支援的查詢模式
下列查詢模式無法加速,會自動改回標準的逐列執行:
- 巢狀 AI 函式:AI 函式無法將另一個 AI 函式呼叫做為引數 (例如
ai.if(ai.if(...)))。 - 外部彙整
ON子句:AI 函式位於LEFT、RIGHT或FULL OUTER JOIN條件中。解決方法是將 AI 篩選器放在WHERE子句或子查詢中。 - 匯總函式包裝 AI 函式:直接匯總 AI 函式 (例如
AVG(ai.rank(...)))。解決方法是先在 CTE 或子查詢中計算 AI 函式,然後再匯總。 - 易變函式引數:包含易變函式的引數運算式 (例如
random()或clock_timestamp())。 - 非常數引數:初始文字輸入後的所有引數 (例如
output_schema、categories和model_id) 都必須是常數文字,而非資料欄參照或運算式。 - 關聯子查詢或外部參數:參照外部查詢區塊變數的 AI 運算式。
- 非基本關係:掃描外部資料表 (
postgres_fdw) 或具體化 CTE (WITH ... AS MATERIALIZED)。 - 超過五個不同的 AI 函式:單一資料表掃描最多支援五個不同的 AI 函式呼叫。
調整效能
您可以調整 AlloyDB 執行個體和工作階段參數,盡可能提高 AI 工作負載的處理量,並縮短延遲時間。
批次群組大小
參數 google_ml_integration.ai_function_acceleration_group_size 會設定批次處理至 Vertex AI 的單一遠端 RPC 呼叫中的資料列數量上限:
- 預設值:
4000(範圍:1至20000) - 範圍:工作階段、使用者或資料庫層級
SET google_ml_integration.ai_function_acceleration_group_size = 10000;
工作負載規模調整指南:
- 互動式查詢 (用於線上交易處理 (OLTP) 或低延遲):將
group_size設為50至100之間。如果查詢含有LIMIT子句,較小的批次大小會更快傳回第一批結果。 - 大量處理或分析管道 (適用於線上分析處理 (OLAP) 或擷取、轉換和載入 (ETL) 工作負載):將
group_size設為5000至20000之間。較大的批次可最大化模型處理量,並盡可能縮短大型資料集的整體查詢執行時間。
管理並行和 worker
平行查詢執行功能會將批次評估作業分配給 Gather 節點下的背景工作站。如要最佳化平行處理量,請考量下列事項:
- 如要執行大量分析掃描,請務必適當設定
max_parallel_workers_per_gather和max_parallel_workers,盡可能提高平行處理的處理量。 - 如果是互動式工作負載,或 Vertex AI 頻率限制嚴格的環境,減少 worker 數量可避免並行查詢爭用模型配額。
管理個人化記憶
智慧批次處理功能會使用 PostgreSQL 的 work_mem 設定,自動限制記憶體用量,並在達到記憶體門檻時動態調度批次,避免資源消耗過多。如果處理非常大的文字提示詞或批次,請確保 work_mem 大小適當。
實現最佳成本效益
只有通過所有非 AI 關聯式述詞的資料列,才會傳送至模型。只要查詢語意允許,套用選擇性關聯 SQL 篩選器 (例如日期範圍、狀態碼或類別篩選器),就能減少傳送至模型的候選資料列數量。這可降低模型叫用成本和執行延遲時間。
疑難排解
以下各節說明執行加速 AI 查詢時的常見問題和修正步驟。
查詢未使用加速功能
如果查詢未使用智慧批次處理,但您希望使用,請考慮下列事項:
- 檢查擴充功能旗標:確認
SHOW google_ml_integration.enable_ai_function_acceleration;傳回on。 - 檢查不支援的模式:確認查詢不含任何不支援的查詢模式。
執行
DEBUG2診斷:依序執行SET client_min_messages TO DEBUG2;和EXPLAIN SELECT ...;,查看略過 AI 函式加速功能的具體原因。請務必在執行EXPLAIN後立即執行RESET client_min_messages;,以免在正常查詢作業期間,工作階段中充斥偵錯訊息。例如:SET client_min_messages TO DEBUG2; EXPLAIN SELECT ...; RESET client_min_messages;預備陳述式:PostgreSQL 會快取預備陳述式的查詢計畫。如果您切換了加速旗標,請執行
DEALLOCATE ALL;重新編譯快取的計畫。
處理配額用盡的情況
如果遇到 HTTP 429 或頻率限制錯誤,可能是因為智慧批次處理同時處理過多資料列,導致 API 耗用量增加。為避免配額用盡,請考慮下列事項:
- 權杖配額 (TPM):確認 Google Cloud 專案在目標區域中,有足夠的目標模型每分鐘權杖數 (TPM) 配額。如要提高 TPM 配額,請參閱「要求調整 TPM 配額」。
- Agent Platform API 頻率限制:確認 Google Cloud 專案有足夠的 Agent Platform API 配額。如要申請提高 Agent Platform 模型的配額,請參閱「申請提高 API 配額」。
平行查詢:如果平行 worker 耗盡 Agent Platform 配額,請降低工作階段的平行處理量:
SET max_parallel_workers_per_gather = 0;非平行查詢:如果非平行查詢受到頻率限制,請縮減批次群組大小:
SET google_ml_integration.ai_function_acceleration_group_size = 500;