AI_FILTER - Hologres

AI_FILTER 是 Hologres 提供的 AI Function，用於在 SQL 中直接對文本或檔案進行「真/假」的語義判斷，返回 BOOLEAN 結果。本文為您介紹 AI_FILTER 的使用限制、文法和使用樣本。

功能介紹

AI_FILTER 將大語言模型的語義理解能力封裝成一個標準的布爾函數，可以用在 SELECT 列表、WHERE 過濾條件、JOIN ON 關聯條件等任意需要布爾值的位置，無需額外的 UDF 或外部服務整合。

典型使用情境如下：

評論、反饋的情感或意圖篩選，例如判斷「客戶是否滿意」。
內容合規、垃圾資訊、敏感內容判斷。
在沒有外鍵關係時，基於語義做關聯 JOIN。
圖片內容識別，例如判斷「圖片中是否包含貓」。

使用限制

版本要求：僅 Hologres V4.2.12 及以上版本支援。
需先部署託管模型：使用前需在 Hologres 控制台部署託管模型。具體操作，請參見託管模型。
return_error_details 參數：只接受省略或 TRUE。省略時，出錯的行返回 NULL；取值為 TRUE 時，返回 OBJECT 類型的 {"value": ..., "error": ...}；取值為 FALSE 時不被接受，會直接報錯並提示改用不帶該參數的重載。
行級容錯：批量處理多行時，出錯的行返回 NULL，不會中斷整個查詢。
結果非確定性：布爾結果由模型的語義判斷決定，同一輸入在不同模型或不同模型版本下可能存在差異，不保證結果完全一致。

文法

-- 文法一：對輸入文本做布爾判斷
AI_FILTER( <model_name>, <input> [, <return_error_details> ] )

-- 文法二：對單個檔案（如圖片）做布爾判斷
AI_FILTER( <model_name>, <predicate>, <file> [, <return_error_details> ] )

-- 文法三：使用 PROMPT 模板拼裝多列、混合文本與檔案的輸入
AI_FILTER( <model_name>, PROMPT('<template_string>', <col_1>, ... ) [, <return_error_details> ] )

參數說明

參數名	參數含義	是否必填
`model_name`	模型名，TEXT 類型。	是
`input`	待判斷的文本陳述，TEXT 類型。函數會在陳述前自動拼接一段「判斷以下陳述為 TRUE 還是 FALSE」的提示詞，由模型返回布爾結果。	是
`predicate`	判斷指令，TEXT 類型，描述如何對 `file` 做布爾分類，例如 `'圖片中是否包含貓？'`。	是
`file`	待判斷的檔案列，FILE 類型。可以使用 IMAGE FILE 作為輸入，通過 `to_file()` 或 Object Table 提供。	是
`PROMPT('<template_string>', <col_1>, ...)`	對於複雜提示詞，尤其是多列或混合文本與檔案的情境，使用 `PROMPT()` 拼裝輸入，支援文本與 FILE 類型的格式化。	是
`return_error_details`	布爾標誌，BOOLEAN 類型，指示出錯時是否返回錯誤詳情。省略時，出錯返回 `NULL`；取值為 `TRUE` 時，返回 OBJECT 類型的 `{"value": ..., "error": ...}`；取值為 `FALSE` 時不被接受並報錯。	否

錯誤行為

預設情況下，如果 AI_FILTER 無法處理某一行輸入，該行返回 NULL，查詢繼續執行，不會中斷。傳回值取決於 return_error_details 參數。

return_error_details 取值	傳回值	說明
省略或 TRUE（執行成功）	BOOLEAN 類型的 `true` 或 `false`，或 OBJECT 類型的 `{"value": bool, "error": null}`	正常結果。
省略（執行失敗）	`NULL`	行級錯誤，查詢繼續執行。
TRUE（執行失敗）	`{"value": null, "error": "<msg>"}`	錯誤詳情作為 OBJECT 返回。
FALSE	報錯	不支援該取值，報錯並引導改用不帶該參數的重載。

傳入 FALSE 時的報錯資訊如下：

ERROR: ai_filter: return_error_details must be TRUE when specified;
       use ai_filter(model_name, input) for BOOLEAN output
HINT:  Call ai_filter(model_name, input) to get a BOOLEAN result on error (NULL).

使用樣本

以下樣本均使用 Hologres 託管模型 qwen3.8-max 執行。

樣本一：對輸入文本應用 AI_FILTER

SELECT ai_filter('qwen3.8-max', '天空是藍色的');

返回結果：

+------+
| ?    |
+------+
| t    |
+------+

樣本二：在 WHERE 子句中做語義過濾

篩選出表達正面評價的訂單評論。

SELECT order_id, order_comments
FROM (VALUES
  (1, '品質很好，物流也快，非常滿意'),
  (2, '封裝破損，客服態度差'),
  (3, '一般般，湊合用')
) AS orders(order_id, order_comments)
WHERE ai_filter('qwen3.8-max', '客戶是否喜歡這個商品:' || order_comments);

返回結果：

+----------+----------------------------------------+
| order_id | order_comments                         |
+----------+----------------------------------------+
|        1 | 品質很好，物流也快，非常滿意            |
+----------+----------------------------------------+

樣本三：使用 PROMPT 函數拼裝輸入

SELECT ai_filter(
  'qwen3.8-max',
  prompt('{0} 是否被描述為 {1}？', '無線滑鼠', '一款黑色的人體工學滑鼠')
) AS consistent;

返回結果：

consistent
---------
f

樣本四：在 JOIN 條件中做語義關聯

投訴表中沒有部門 ID，無法使用傳統外鍵 JOIN。此時可以用 AI_FILTER 判斷某條投訴是否應由某個部門處理，並將其作為 JOIN 條件。

SELECT t.ticket_id, t.issue_text, d.department_name
FROM (VALUES
  (201, '手機螢幕碎了，想申請保修維修'),
  (202, '扣款成功了但訂單狀態一直沒更新'),
  (203, '登入時收不到簡訊驗證碼')
) AS t(ticket_id, issue_text)
JOIN (VALUES
  ('售後服務'),
  ('訂單營運'),
  ('帳號支援')
) AS d(department_name)
ON ai_filter(
  'qwen3.8-max',
  prompt('下面這條使用者問題是否應該由"{0}"負責處理？只根據語義判斷。使用者問題：{1}',
         d.department_name, t.issue_text)
);

返回結果：

ticket_id | issue_text                     | department_name
----------|--------------------------------|----------------
      201 | 手機螢幕碎了，想申請保修維修     | 售後服務
      202 | 扣款成功了但訂單狀態一直沒更新   | 售後服務
      202 | 扣款成功了但訂單狀態一直沒更新   | 訂單營運
      203 | 登入時收不到簡訊驗證碼           | 帳號支援

樣本五：對圖片檔案應用 AI_FILTER

SELECT id,
       ai_filter(
         'qwen3.8-max',
         '圖片中是否包含貓？',
         to_file(img_path, 'oss-cn-hangzhou-internal.aliyuncs.com', 'acs:ram::<ACCOUNT_ID>:role/<ROLE_NAME>')
       ) AS has_cat
FROM (VALUES
  (1, 'oss://my-bucket/cat.png'),
  (2, 'oss://my-bucket/dog.png')
) AS images(id, img_path);

返回結果：

+----+---------+
| id | has_cat |
+----+---------+
|  1 | t       |
|  2 | f       |
+----+---------+

樣本六：返回錯誤詳情

將 return_error_details 設定為 TRUE，返回 OBJECT 類型的結果。

SELECT ai_filter('qwen3.8-max', '水在100攝氏度沸騰', TRUE) AS result;

返回結果：

+----------------------------------+
| result                           |
+----------------------------------+
| {"value": true, "error": null}   |
+----------------------------------+

說明

如需 BOOLEAN 類型的輸出，請省略 return_error_details 參數。傳入 FALSE 會直接報錯。