AI Function - Hologres

Hologres自V3. 2版本起正式支援AI Function，並提供了Embedding、Rank和LLM等運算元。您可通過標準SQL直接調用AI Function，無需額外推理服務，實現企業級知識庫構建與推理等AI情境。

前提條件

已購買AI資源。
已部署模型。

AI Function匯總表

當前Hologres支援AI Function如下表：

每個AI Function會根據部署的模型，預設分配一個最佳的模型，可以通過系統資料表查看AI Function預設分配的模型。
調用AI Function時可以不需要填寫模型名稱，系統會自動使用預設的模型。如果需要更換AI Function對應的模型，需要通過系統資料表更改，詳情請參見修改AI Function對應的模型。
每個模型部署時需要的AI資源不同，請根據業務需要購買合適的規格。

Function名稱	描述	支援的模型	支援的版本
to_file	將一個URL轉成FILE類型。	無需模型，通常適配Object Table一起使用。	V4.0及以上版本支援
prompt	拼裝大模型提示詞，可以封裝多模態提示詞。	無需模型。
ai_parse_document	將非結構化PDF、圖片等資料解析成文本。	ds4sd/docling-models。
ai_embed	對給定的文本、圖片計算一個固定維度連續向量。	文本類： iic/nlp_gte_sentence-embedding_chinese系列。 Qwen/Qwen3-Embedding-XB系列。圖片類：clip-ViT-B系列。	V3.2及以上版本支文本向量 V4.0及以上版本支援圖片向量
ai_rank	對給定的文本進行相關性打分。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。	V3.2.2及以上版本
ai_chunk	長文本分段。	recursive-character-text-splitter。	V3.2.2及以上版本
ai_gen	通過提示詞調用大語言模型對文本、圖片進行推理並輸出結果。	文本類：Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。圖片類：Qwen/Qwen2.5-VL-xB類型。	V3.2及以上版本支援文本推理 V4.0及以上版本支援圖片推理
ai_classify	根據提供的分類標籤對輸入文本進行分類。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。	V3.2及以上版本
ai_extract	從輸入文本中提取指定的標籤資訊。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_mask	從輸入文本中將指定的標籤資訊脫敏，資訊脫敏後用`[MASKED]`做預留位置。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_fix_grammar	用於修複輸入文本的語法錯誤。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_summarize	產生一段文本的摘要。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_translate	將輸入文本翻譯成指定的語言。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_similarity	計算兩個輸入文本的相似性。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。
ai_analyze_sentiment	對輸入的文本進行情感分析。	Qwen3系列大模型，推薦使用Qwen/Qwen3-32B。 iic/nlp_structbert_sentiment-classification_chinese-base模型。

AI Function使用

ai_embed

描述：對輸入的文本、圖片計算一個固定維度連續向量

--計算文本向量
select ai_embed([model,] content);
--計算圖片向量
select ai_embed([model,] file);

參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，輸入的文本，支援字元類型（CHAR、VARCHAR、TEXT）。
- file：必填，FILE類型，一般是輸入IMAGE的FILE對象。僅Hologres V4.0及之後版本支援該類型。

傳回值說明

若content參數值為NULL或者Null 字元串，則返回NULL。
如果FILE是NULL，則返回NULL。

根據調用的模型，返回對應的向量維度。支援的模型和返迴向量維度如下：

模型名稱	分類	返回的向量維度	支援的Hologres版本
clip-ViT-B-32	圖片向量	映像分塊 patch size：32 * 32 參數量：88 M 返迴向量維度：512	V4.0及以上版本
clip-ViT-B-32-multilingual-v1 說明輸入不支援圖片，圖片需繼續使用clip-ViT-B-32。	文本向量	映像分塊 patch size：32 * 32 參數量：88 M 返迴向量維度：512
clip-ViT-B-16	圖片向量	映像分塊 patch size：16 * 16 參數量：88 M 返迴向量維度：512
clip-ViT-L-14	圖片向量	映像分塊 patch size：14 * 14 參數量：304 M 返迴向量維度：768
iic/nlp_gte_sentence-embedding_chinese-base	文本向量	512	V3.2及以上版本
iic/nlp_gte_sentence-embedding_chinese-large	文本向量	768
iic/nlp_gte_sentence-embedding_chinese-small	文本向量	1024
Qwen/Qwen3-Embedding-0.6B	文本向量	1024
Qwen/Qwen3-Embedding-4B	文本向量	2560
Qwen/Qwen3-Embedding-8B	文本向量	4096

使用樣本

文本Embeding

SELECT ai_embed('Hologres是阿里巴巴自主研發的一站式即時數倉引擎，支援海量資料即時寫入、即時更新、即時加工、即時分析.');

返回結果如下。

ai_embed
-------
{-0.020090256, -0.009496426, -0.01584659, ..., -0.057956327}

圖片Embedding

--圖片embedding，樣本將一張oss上的圖片embedding
SELECT ai_embed('clip-ViT-B-32', to_file('oss://****', 'oss-cn-hangzhou-internal.aliyuncs.com', 'roleran'));

ai_rank

描述：對給定的文檔進行相關性打分。

SELECT ai_rank([model,] source_sentence, sentence_to_compare);

參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- source_sentence：必填，常值內容，支援字元類型（CHAR、VARCHAR、TEXT）。
- sentence_to_compare：必填，與source_sentence參數值進行對比的語句，支援字元類型（CHAR、VARCHAR、TEXT）。
傳回值說明
- 返回FLOAT類型的相關性Score，取值區間：[0, 1]，值越大相關性越高。
- 若source_sentence和sentence_to_compare參數其中一個值為NULL時，返回0。

使用樣本

SELECT knowledge, ai_rank('阿里巴巴2024年營收是多少？', knowledge) AS score
  FROM (
      VALUES ('Amazon 2024年營收6380億美元'), 
             ('Alibaba 2024年營收9411.68億元'), 
             ('阿里巴巴2023年的營收8686.87億元')
  ) AS knowledge_table(knowledge)
  ORDER BY score DESC;

返回結果如下。

knowledge	                  ｜ score
-----------------------------｜-------
Alibaba 2024年營收9411.68億元	 ｜0.899999976
阿里巴巴2023年的營收8686.87億元 ｜0.200000003
Amazon 2024年營收6380億美元	   ｜0.100000001

ai_chunk

描述：對長文本進行分段（切片）。

SELECT ai_chunk([model,] long_sentence[, chunk_size, chunk_overlap, separators])

參數說明

參數名稱	說明
model	可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
long_sentence	必填，需要分段的源文本，支援字元類型（CHAR、VARCHAR、TEXT）。
chunk_size	可選，每個分段的Chunk長度，支援INT類型，預設值是300。
chunk_overlap	可選，相鄰Chunk的Overlap長度，避免句子切到不同Chunk破壞語義，支援INT類型，預設值是50。
separators	可選，切分Chunk的分隔字元，TEXT[]類型。預設值是`["\n\n", "\n", " ", ""]`，適用於處理英文文本。如果是中文文字建議使用中文分隔字元`["\n\n", "\n", "。", "！", "？", "；", "，", " "]`。

傳回值說明
- 返回TEXT[]類型，表示分割好的Chunks列表。
- 若long_sentence參數值為None時，則返回None。

使用樣本

SELECT ai_chunk('Hologres是阿里巴巴自主研發的一站式即時數倉引擎（Real-Time Data Warehouse），支援海量資料即時寫入、即時更新、即時加工、即時分析，支援標準SQL（相容PostgreSQL協議和文法，支援大部分PostgreSQL函數），支援PB級資料多維分析（OLAP）與即席分析（Ad Hoc），支援高並發低延遲的線上資料服務（Serving），支援多種負載的細粒度隔離與企業級安全能力，與MaxCompute、Flink、DataWorks深度融合，提供企業級離線上一體化全棧數倉解決方案。',40,10);

返回結果如下。

ai_chunk
---
"{"Hologres是阿里巴巴自主研發的一站式即時數倉引擎（Real-Time Data","Warehouse），支援海量資料即時寫入、即時更新、即時加工、即時分析，支援標","工、即時分析，支援標準SQL（相容PostgreSQL協議和文法，支援大部分Po","文法，支援大部分PostgreSQL函數），支援PB級資料多維分析（OLAP）與","維分析（OLAP）與即席分析（Ad","Hoc），支援高並發低延遲的線上資料服務（Serving），支援多種負載的細粒度","支援多種負載的細粒度隔離與企業級安全能力，與MaxCompute、Flink、D","te、Flink、DataWorks深度融合，提供企業級離線上一體化全棧數倉解","線一體化全棧數倉解決方案。"}"

ai_gen

描述：通過提示詞調用大語言模型對文本、圖片進行推理並輸出結果。

--文本推理
SELECT ai_gen([model,] text)
--圖片推理
SELECT ai_gen([model,] text, file)
--封裝提示詞
SELECT ai_gen([model,] prompt)

參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- text：必填，待輸入的提示詞，支援字元類型（CHAR、VARCHAR、TEXT）。
- file：必填，FILE類型，如圖片通過Object Table轉成FILE類型，僅Hologres V4.0及以上版本支援該參數。
- prompt：必填，JSON類型，prompt()函數的傳回值。
傳回值說明
- 返回大模型對該問題的回答。
- 若text參數值為NULL時，則返回NULL；
- 若text參數值為空白字串（""）時，則返回Null 字元串（""）。
- 當 prompt參數值為NULL，則報錯。

使用樣本

文本推理

CREATE TABLE questions (
    question TEXT
);

INSERT INTO questions (question) VALUES
  ('什麼是人工智慧？'),
  ('如何提高英語口語水平？'),
  ('健康飲食有哪些注意事項？');

SELECT
  question,
  ai_gen('請用 20 個字回答如下問題: ' || question) AS answer
FROM
  questions;

返回結果如下。

 question            ｜	answer
  --------------------｜-------
如何提高英語口語水平？	  ｜多說多練，模仿發音，積累詞彙，勇於開口。
健康飲食有哪些注意事項？	｜均衡搭配，控制油鹽糖，多蔬果，少加工，適量飲水，規律飲食。
什麼是人工智慧？	        ｜人工智慧是類比人類智能的電腦系統，能學習、推理、感知和解決問題。

圖片推理

SELECT  ai_gen('jpg_llm','這張圖片中有什麼?', to_file('oss://****/bd****k/val/images/b9b53753-91a5****.jpg','oss-cn-hangzhou-internal.aliyuncs.com','acs:ram::****' ) )

返回結果如下。

ai_gen
-----
這張圖片顯示了一條城市街道的情境。可以看到一輛白色的車停在路邊，車牌號是BTB-9784。街道上有幾輛汽車，包括一輛黃色的出租車。背景中有建築物和樹木，天氣看起來有些陰沉，可能是下雨天。街道上還有行人和交通號誌。

ai_classify

描述：根據提供的分類標籤對輸入文本進行分類。
```
SELECT ai_classify([model,] content, labels)
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，需要分類的文本，支援字元類型（CHAR、VARCHAR、TEXT）。
- labels：必填，表示期望輸出的分類標籤列表，標籤數量須在2~20之間，支援ARRAY類型。
傳回值說明
- 返回分類結果，即匹配的標籤。傳回值類型為TEXT。
- 若content參數值為NULL時，則返回NULL。
- 若content是Null 字元串（""）時，則返回NULL。
- 若labels參數值數量不正確時，將報錯。

使用樣本

CREATE TABLE product_detail(
    product_name TEXT,
    product_desc TEXT
);
INSERT INTO product_detail VALUES
('iphone','蘋果手機'),
('p50','華為手機'),
('x200','vivo手機'),
('aaa','Dior連衣裙'),
('bbb','Dior褲子'),
('聲聲烏龍','茶顏悅色的奶茶'),
('夾心餅乾','奧利奧的餅乾');

--用ai_classify對文本分類
SELECT
    product_name,
    ai_classify(product_desc, ARRAY['電子產品', '服裝', '食品']) AS category
  FROM
     product_detail
  LIMIT 10;

返回結果如下。

product_name	｜category
--------------｜------
aaa	          ｜服裝
iphone	      ｜電子產品
聲聲烏龍	      ｜食品
p50	          ｜電子產品
x200	        ｜電子產品
bbb	          ｜服裝
夾心餅乾	      ｜食品

ai_extract

描述：從輸入文本中提取指定的標籤資訊。
```
SELECT ai_extract([model,] content, labels)
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，需輸入的文本資訊，支援字元類型（CHAR、VARCHAR、TEXT）。
- labels：必填，指定的標籤資訊，標籤數量須在1~20之間，支援ARRAY類型。
傳回值說明
- 返回每個Label對應的提取資訊，為JSON格式。
- 若content參數值為NULL或Null 字元串（""）時，則返回NULL。
- 若labels參數值數量不正確時，將報錯。

使用樣本

CREATE TABLE users (
  user_id TEXT,
  resume TEXT
);

INSERT INTO users (user_id, resume) VALUES
  ('u001', '姓名：張三，男，28歲。郵箱：zhangsan@example.com，電話：1380013****。工作經驗豐富。'),
  ('u002', '姓名：李四，女，35歲。電話：1390013****，郵箱：lisi@example.com。具有管理經驗。'),
  ('u003', '姓名：王五，男，25歲。郵箱：wangwu@example.com。電話：1370013****。');

SELECT
  user_id,
  ai_extract(resume, ARRAY['姓名','郵箱','電話','性別','年齡']) AS user_desc_obj
FROM
  users;

返回結果如下。

user_id	｜user_desc_obj
--------｜-------------
u002	  ｜"{"姓名":"李四","年齡":"35歲","性別":"女","電話":"1390013****","郵箱":"lisi@example.com"}"
u003	  ｜"{"姓名":"王五","年齡":"25歲","性別":"男","電話":"1370013****","郵箱":"wangwu@example.com"}"
u001	  ｜"{"姓名":"張三","年齡":"28歲","性別":"男","電話":"1380013****","郵箱":"zhangsan@example.com"}"

ai_mask

描述：從輸入文本中將指定的標籤資訊脫敏，資訊脫敏後用[MASKED]做預留位置。
```
SELECT ai_mask([model,] content, labels)
```
參數說明：
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，需要脫敏的輸入文本，支援字元類型（CHAR、VARCHAR、TEXT）。
- labels：必填，需要脫敏的標籤資訊，標籤數量須在1~20之間，支援ARRAY類型。
傳回值說明
- 返回脫敏後的常值內容。
- 若content參數值為NULL時，則返回NULL。
- 若content參數值為空白字串（""）時，則返回Null 字元串。
- 當labels參數值數量不正確，將報錯。

使用樣本

SELECT ai_mask(
  '使用者王小明，社會安全號碼：23030611111111，手機號：1388888****。',
  ARRAY['身份證', '手機號']);

返回結果如下。

ai_mask
-------
使用者王小明，社會安全號碼：[MASKED]，手機號：[MASKED]。

ai_fix_grammar

描述：用於修複輸入文本的語法錯誤。
```
SELECT ai_fix_grammar([model,] content)
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，需要修複文法的輸入文本，支援字元類型（CHAR、VARCHAR、TEXT）。
傳回值說明
- 返回修正後的常值內容。
- 若content參數值為NULL時，則返回NULL。
- 若content參數值為空白字串（""）時，則返回Null 字元串（""）。

使用樣本

SELECT ai_fix_grammar('He dont know what to did.');

返回結果如下。

ai_fix_grammar
--------------
He doesn't know what to do.

ai_summarize

描述：根據輸入的文本，產生一段文本的摘要。
```
SELECT ai_summarize([model,] content[, max_words])
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，輸入文本，支援字元類型（CHAR、VARCHAR、TEXT）。
- max_words：可選，大模型最多輸出的字數，模型將依據該值盡量接近輸出結果。預設值為50，若設定為0，則表示不做任何限制。
傳回值說明
- 返迴文本的摘要。
- 若content參數值為NULL時，則返回NULL。
- 若content參數值為空白字串（""）時，則返回Null 字元串（""）。
- 若max_words若取值小於0時，將報錯。

使用樣本

SELECT ai_summarize('Hologres是阿里巴巴自主研發的一站式即時數倉引擎（Real-Time Data Warehouse），支援海量資料即時寫入、即時更新、即時加工、即時分析，支援標準SQL（相容PostgreSQL協議和文法，支援大部分PostgreSQL函數），支援PB級資料多維分析（OLAP）與即席分析（Ad Hoc），支援高並發低延遲的線上資料服務（Serving），支援多種負載的細粒度隔離與企業級安全能力，與MaxCompute、Flink、DataWorks深度融合，提供企業級離線上一體化全棧數倉解決方案。', 15);

返回結果如下。

ai_summarize
------------
Hologres是阿里自主研發的即時數倉引擎，支援海量資料即時處理與多維分析。

ai_translate

描述：將輸入文本翻譯成指定的語言。
```
SELECT ai_translate([model,] content, to_lang)
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，輸入需翻譯的文本，支援字元類型（CHAR、VARCHAR、TEXT）。
- to_lang：必填，目標語言Code。詳情，請參見ISO-639。
傳回值說明
- 返回翻譯後的文本。
- 若content參數值為NULL時，則返回NULL。
- 若content參數值為空白字串（""）時，則返回Null 字元串（""）。
- 若to_lang參數值非法時，則報錯。

使用樣本

SELECT ai_translate('Hologres是阿里巴巴自主研發的一站式即時數倉引擎（Real-Time Data Warehouse），支援海量資料即時寫入、即時更新、即時加工、即時分析，支援標準SQL（相容PostgreSQL協議和文法，支援大部分PostgreSQL函數），支援PB級資料多維分析（OLAP）與即席分析（Ad Hoc），支援高並發低延遲的線上資料服務（Serving），支援多種負載的細粒度隔離與企業級安全能力，與MaxCompute、Flink、DataWorks深度融合，提供企業級離線上一體化全棧數倉解決方案。', 'en');

返回結果如下。

ai_translate
-----------
Hologres is a self-developed one-stop real-time data warehouse engine by Alibaba, supporting real-time writing, real-time updating, real-time processing, and real-time analysis of massive data. It supports standard SQL (compatible with PostgreSQL protocol and syntax, supporting most PostgreSQL functions), supports multi-dimensional analysis (OLAP) and ad-hoc analysis at the PB-level, supports high-concurrency, low-latency online data services (Serving), supports fine-grained isolation for multiple workloads and enterprise-level security capabilities, and is deeply integrated with MaxCompute, Flink, and DataWorks, providing an enterprise-level fully stacked data warehouse solution that integrates online and offline processing.

ai_similarity

描述：計算兩個輸入文本的相似性。
```
SELECT ai_similarity([model,] text1, text2)
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- text1和text2：需要對比相似性的兩個文本，支援字元類型（CHAR、VARCHAR、TEXT）。
傳回值說明
- 返回區間[0, 1]之間的FLOAT類型的數值，值越大相似性越高。0表示完全不相似，1表示兩個文本相等。
- 若text1和text2參數中有一個值為NULL時，則返回0。
- 若text1和text2參數值均為空白字串（""）時，則返回1。
- 若text1和text2參數中一個值為空白字串（""），另外一個為非Null 字元串時，則返回0。

使用樣本

CREATE TABLE products2 (
    product_name TEXT
);

INSERT INTO products2 (product_name) VALUES
  ('白色襯衫'), ('黑色西裝褲'), ('休閑上衣'), ('運動外套'), ('白色連衣裙'),
  ('藍芽耳機'), ('牛奶巧克力'), ('白色上衣'), ('男士T恤'), ('羽絨服');

SELECT product_name FROM products2 
  ORDER BY ai_similarity(product_name, '白色上衣') DESC LIMIT 5;

返回結果如下。

product_name
----------
白色上衣
白色襯衫
休閑上衣
白色連衣裙
男士T恤

ai_analyze_sentiment

描述：對輸入的文本進行情感分析。
```
select ai_analyze_sentiment([model,] content);
```
參數說明
- model：可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
- content：必填，輸入的文本，支援字元類型（CHAR、VARCHAR、TEXT）。
傳回值說明
- 返回分析之後的情感Labels，為字元類型。不同的模型，返回的Labels內容有區別。
  - Qwen3系列大模型，返回標籤是： positive/negative/neutral/mixed中的一種，輸入為空白時返回 NULL。
  - iic/nlp_structbert_sentiment-classification_chinese-base模型：返回機率最高的標籤：正面/負面/NULL 中的一種，輸入為空白時返回 NULL。
- 若content參數值為NULL或者Null 字元串（""）時，則返回NULL。

使用樣本

--大語言模型：
SELECT ai_analyze_sentiment('洞房花燭夜，金榜提名時。');
-- output example: positive

--使用iic/nlp_structbert_sentiment-classification_chinese-base模型
SELECT ai_analyze_sentiment('清明時節雨紛紛，路上行人慾斷魂。');
-- output example: 負面

ai_parse_document

描述：支援將非結構化資料（PDF、圖片、Word、PPT、TXT、Markdown）等多種格式的資料解析成文本。

SELECT ai_parse_document([model,] input_bytes , input_format [, output_format]);
SELECT ai_parse_document([model,] file [, input_format, output_format]);

參數說明

參數名稱	說明
model	可選，AI Function使用的模型名稱。預設由系統根據已部署的模型自動分配最佳模型。如需更換模型，應先完成目標模型的部署，再修改系統資料表配置。具體操作，請參見修改AI Function對應的模型。
input_bytes	必填，BYTEA類型，需要解析檔案的BINARY。
file	必填，File類型，通常建議配合Object Table一起使用。
input_format	可選，預設值為auto，TEXT類型。支援的檔案格式PDF、Word、PPT、TXT、IMAGE、AUTO等格式。圖片格式支援：`["jpg", "jpeg", "png", "tif", "tiff", "bmp"]`。當一個OSS目錄有多種不同類型的文檔時，可以設定`input_format=auto` ，模型將根據副檔名來自動判斷檔案類型。
output_format	可選，預設值 JSON。解析結果的格式，text類型，支援 JSON、markdown等格式。

傳回值說明
返回text類。會根據output_format的設定返回對應的格式。
- 如果 output_format=JSON, 輸出是 text 類型JSON 字串，需要使用時顯示 cast 成 JSON
- 當解析失敗時，返回錯誤的text，而不是報錯。

使用樣本

將OSS中的單個PDF檔案轉成文本。

SELECT object_uri, etag, ai_parse_document(to_file ('oss://xxxx-hangzhou/bs_challenge_financial_14b_dataset/pdf', 'oss-cn-hangzhou-internal.aliyuncs.com', 'acs:ram::18xxx:role/xxx'), 'auto', 'markdown') AS doc 
    FROM pdf_bs_challenge_financial_14b_dataset limit 1);

將Object Table的非結構化資料轉成文本，詳細使用見非結構化資料（Object Table）。

prompt

描述：此工具函數是AI Function的輔助函數，用於拼裝大模型提示詞，可以包含多模態的提示詞。
```
SELECT prompt('<template_string>', <expr_1> [ , <expr_2>, ... ])
    FROM <table>;
```
使用說明
不支援標量字串。若僅有一條字串，應直接傳遞給大模型，避免使用prompt函數，一般是FROM表使用。
參數說明
- template_string：必填，TEXT類型，提示詞模板STRING，變數使用{0}，{1}做預留位置。
- <expr_1> [ , <expr_2>, ... ]：多個運算式參數。支援TEXT、NUMBERIC、FILE等類型。
傳回值說明
通常情況下返回JSON類型，格式如下：
```
{
  "prompt": "<template_string>",
  "args": ARRAY(<value_1>, <value_2>, ...)
}
```
特殊情況下：
- 若template_string參數值為NULL，則報錯。
- expr返回NULL的時候，template_string中以字串None代替。
- 返回結果中某一行全為NULL，將不會過濾該行，而是Args中全部填充None。

使用樣本

create table customer_service_konwledge_detail(
  question text, 
  question_summarize text
);

insert into customer_service_konwledge_detail values
('執行個體突然出現很多OOM的SQL', '後台排查到是由於客戶的訪問量增加，現有的資源不足以支撐該訪問流量，客戶已經擴容解決'),
('Dataworks串連不上hologres了', '這不是我們的問題，請聯絡Dataworks值班');

-- prompt
SELECT question, question_summarize, ai_gen(
  prompt('客戶提的工單內容：{0}, 阿Cloud Customer Service System給的回答: {1}，請問該回答是否解決了客戶問題？只輸出是或否', question, question_summarize)) 
      from customer_service_konwledge_detail;

返回結果如下。

          question           |                                 question_summarize                                 | ai_gen 
-----------------------------+------------------------------------------------------------------------------------+--------
 Dataworks串連不上hologres了 | 這不是我們的問題，請聯絡Dataworks值班                                              | 否
 執行個體突然出現很多OOM的SQL    | 後台排查到是由於客戶的訪問量增加，現有的資源不足
以支撐該訪問流量，客戶已經擴容解決 | 是
(2 rows)

to_file

描述：此工具函數可以將一個URL轉成FILE類型。
```
select to_file(oss_url, oss_endpoint, oss_rolearn);
```
使用說明
該函數是一個工具函數，無需使用模型。
參數說明
- oss_url: 必填， text類型，需要解析的OSS檔案路徑。
- oss_endpoint: 必填，text類型, 填寫OSS Region網域名稱，僅支援傳統網路網域名稱。
- oss_rolearn: 必填，訪問OSS的RoleARN資訊。
傳回值說明
返回FILE類型，如果URL檔案路徑非法或者檔案不存在，則報錯。

使用樣本

select to_file('oss://****/bd****k/val/images/b9b53753-91a5****.jpg','oss-cn-hangzhou-internal.aliyuncs.com','acs:ram::****' );

AI Function與模型

查看Function與模型的映射關係

Hologres提供list_ai_function_infos系統資料表，用於查看AI Function與模型的映射關係。在Hologres管控台部署模型後，該系統資料表會自動更新每個AI Function對用的模型，您可以通過AI Function調用對應的模型。

說明

不同AI Function需要適配特定類型的模型，例如：ai_embed適合Embedding模型、ai_classify適合大語言模型。若執行個體中僅部署了一種模型，可能會出現部分AI Function分配模型為空白的情況。AI Function沒有部署對應的模型時，將無法使用該AI function。

SELECT * FROM list_ai_function_infos();

返回結果如下。

    function_name     |    model_name    
----------------------+------------------
 ai_embed             | my_gte_embedding
 ai_classify          | my_qwen32b
 ai_extract           | my_qwen32b

修改AI Function對應的模型

AI Function與部署的模型有預設映射值，您可以通過如下方式修改AI Function對應的模型。修改後，使用AI Function時將會調用新的模型。

全域修改
```
SELECT set_ai_function_info('<function_name>', '<model_name>');
```
參數說明
- function_name：AI Function名稱，您可以在AI Function匯總表中查看AI Function名稱。
- model_name：已經部署的模型名稱。您可登入Hologres管理主控台在AI節點頁面，查看已部署的模型名稱。
說明
當輸入的AI Function名稱和已部署模型名稱不存在時，將會報錯。
使用樣本
```
SELECT set_ai_function_info('ai_embed', 'my_gte_embedding');
```
SESSION層級修改
SESSION層級修改後，使用AI Function調用模型時，SESSION層級的配置會優先於全域修改（ai_function_info）的配置。
```
--僅在該串連上生效
SET hg_experimental_ai_function_name_to_model_name_mapping='<function_name>:<model_name>[,<function_name1>:<model_name1>]';
```

最佳實務

瞭解了AI Function的基礎用法後，您可以通過以下真實情境的最佳實務，學習如何將它們組合應用，解決複雜的業務問題。