加快含 AI 函式的查詢執行速度

在 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 函式的智慧批次處理功能,請確認符合下列必要條件:

  1. PostgreSQL 版本:使用 PostgreSQL 17 以上版本。
  2. 與 Gemini Enterprise Agent Platform 整合:完成「與 Gemini Enterprise Agent Platform 整合」中的步驟。
  3. 區域可用性:智慧批次處理功能適用於支援預設模型 (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;
    

後續步驟