ai.classify 函数是一种内置的 AlloyDB AI 工具，可将文本输入分类为您定义的一组类别或标签。通过将此功能直接嵌入到数据库中，AlloyDB for PostgreSQL 可让您处理非结构化数据，而无需构建复杂的提取、转换和加载 (ETL) 流水线或外部服务集成。
文本分类功能具有以下优势：
- 实时分类：使用 SQL 将 Gemini 的世界知识引入企业数据。
- 可伸缩性：支持针对 AI 函数的智能批处理（也称为 AI 函数加速），这是 AlloyDB AI 中的一项自动查询执行优化功能，可在查询执行期间在后台将逐行的单个标量 AI 函数调用透明地分组为批量模型请求。还支持基于数组和基于游标的处理，以高效处理数千行。
- 简单性：提供高级抽象，可自动管理模型调用和数据准备。
AlloyDB AI 的文本分类功能支持多种应用场景，包括：
- 主题分类：为文档或文章分配预定义的主题（例如体育、技术或金融）。
- 垃圾信息检测：将收到的电子邮件、评论或消息识别为垃圾信息。
- 意图识别：确定用户查询背后的目标，例如预订航班、查看天气或订餐。
准备工作
在使用 ai.classify 函数之前，请确保您满足以下要求：
- PostgreSQL 版本：PostgreSQL 18 及更高版本支持
ai.classify函数。确保您的 AlloyDB 集群运行的是 PostgreSQL 18 或更高版本。如需了解详情，请参阅支持的数据库版本。 - 扩展程序版本：确保您已安装最新版本的
google_ml_integration扩展程序（1.6.1或更高版本），并启用了预览功能。
启用扩展程序
确保您已安装最新版本的 google_ml_integration 扩展程序（1.6.1 版或更高版本），并已启用预览功能。
如需在 AlloyDB 中启用 google_ml_integration.enable_ai_query_engine 和 google_ml_integration.enable_preview_ai_functions 标志，请使用 SET 命令。这些标志用于控制对 AI 查询引擎和预览版 AI 函数（例如 ai.classify）的访问权限。
确保您的
google_ml_integration扩展程序版本为1.6.1或更高版本。如需验证版本，请运行以下命令：SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';为当前会话或整个数据库启用标志。如需为当前会话启用这些标志，请运行以下命令：
SET google_ml_integration.enable_ai_query_engine = 'on'; SET google_ml_integration.enable_preview_ai_functions = 'on';此更改不需要重启数据库。这些标志的默认值为
off。
创建示例表
如需按照本文档中的分类函数示例进行操作，请创建一个表，并使用以下示例商品评价填充该表。
CREATE TABLE IF NOT EXISTS product_reviews (
id INT PRIMARY KEY,
review TEXT
);
INSERT INTO product_reviews (id, review) VALUES
(1, 'Fantastic, would buy again!'),
(2, 'Broken on arrival.'),
(3, 'Mediocre, not worth the price.');
对单个字符串进行分类
如需对单个文本输入进行分类，请使用标量版本的 ai.classify。如需查看详细的 API 文档，请参阅 ai.classify 参考文档。
SELECT ai.classify(
input => 'TEXT_CONTENT',
categories => ARRAY['CATEGORY1', 'CATEGORY2', 'CATEGORY3'],
examples => 'EXAMPLES', -- Optional
output_mode => 'OUTPUT_MODE', -- Optional. Can be 'single' or 'multi'.
model_id => 'MODEL_ID' -- Optional. The default value is gemini-3.5-flash-lite.
);
将文本归入互斥的类别
以下示例展示了一个基本用例，即将单段文本分类到多个互斥类别中的一个：
SELECT ai.classify(
input => 'This is a sales report for Q1.',
categories => ARRAY['Report', 'Invoice', 'Memo']
);
以下是示例输出：
Report
对多标签主题进行分类
以下示例通过将 output_mode 设置为 'multi' 并提供类别说明，将新闻标题分类为多个主题：
SELECT ai.classify(
input => 'The government announced new regulations on AI development, citing both economic opportunities and potential security risks.',
categories => ARRAY[
ARRAY['politics', 'Questions about politics'],
ARRAY['technology', 'Questions about technology'],
ARRAY['security', 'Questions about security']
],
output_mode => 'multi'
);
以下是示例输出：
politics,technology,security
使用带有说明的类别
以下示例演示了使用二维数组格式提供类别的首选方式，其中包含标签和说明，以便更清晰地表达：
SELECT ai.classify(
input => 'The patient reported mild fever and headache.',
categories => ARRAY[
ARRAY['urgent', 'Requires immediate medical attention'],
ARRAY['non-urgent', 'Routine check-up or minor symptoms'],
ARRAY['query', 'A question about services or appointments']
]
);
以下是示例输出：
non-urgent
提供少样本示例
以下示例展示了如何通过提供输入示例及其预期输出来引导模型进行分类：
SELECT ai.classify(
input => 'Is this item returnable after 90 days?',
categories => ARRAY[
ARRAY['policy', 'Questions about return, warranty, or other policies'],
ARRAY['shipping', 'Questions about order shipment and delivery'],
ARRAY['payment', 'Questions about payment methods or issues'],
ARRAY['other', 'Any other type of question']
],
examples => '[
{"input": "When will my order arrive?", "output": "shipping"},
{"input": "What is the warranty on this?", "output": "policy"},
{"input": "My discount code isn''t working.", "output": "payment"}
]'
);
以下是示例输出：
policy
使用特定模型 ID
以下示例演示了如何通过引用特定模型版本或类型的 ID 来使用该模型版本或类型：
SELECT ai.classify(
input => 'This new song is a banger!',
categories => ARRAY[
ARRAY['positive', 'Expresses approval or enjoyment'],
ARRAY['negative', 'Expresses disapproval or dislike']
],
model_id => 'MODEL_ID'
);
以下是示例输出：
positive
将 MODEL_ID 替换为受支持的预注册模型或您注册的自定义模型的 ID。如需查看支持的预注册模型列表，请参阅支持的 AI 模型。如需了解如何注册其他模型端点，请参阅使用模型端点管理注册和调用远程 AI 模型。
批量分类
在对多行中的大型数据集进行分类时，您可以使用 AI 函数的智能批处理或使用基于数组的 ai.classify 版本来优化性能。
智能批处理
如需加速跨多行运行标量 ai.classify 的查询，而无需编写复杂的数组聚合查询，请通过将 google_ml_integration.enable_ai_function_acceleration 数据库标志设置为 on 来为 AI 函数启用智能批处理：
SET google_ml_integration.enable_ai_function_acceleration = 'on';
启用此标志后，AlloyDB 会在后台自动将各个标量 ai.classify 调用分组为智能批处理。
SELECT
id,
ai.classify(
input => review,
categories => ARRAY['positive', 'neutral', 'negative']
) AS sentiment
FROM product_reviews
ORDER BY id;
基于数组的批处理
如需明确控制对较大数据集的批量处理，请使用基于数组的 ai.classify 版本，通过传递输入的 SQL 数组来一次处理多个输入。如需查看详细的 API 文档，请参阅 ai.classify 参考文档。
SELECT ai.classify(
inputs => TEXT[],
categories => TEXT[][],
examples => TEXT, -- Optional.
output_mode => VARCHAR, -- Optional. The default value is single.
batch_size => INT, -- Optional. The default value is 10.
model_id => VARCHAR(100) -- Optional. The default value is gemini-3.5-flash-lite.
);
以下示例一次对多条评价进行分类：
SELECT unnest(
ai.classify(
inputs => ARRAY(SELECT review FROM product_reviews ORDER BY id),
categories => ARRAY[
ARRAY['positive', 'Good sentiment'],
ARRAY['neutral', 'Neither good nor bad sentiment'],
ARRAY['negative', 'Bad sentiment']
],
batch_size => 5
)
) AS sentiment;
以下是示例输出：
sentiment
-----------
positive
negative
negative
使用游标进行分类
基于游标的函数可让系统以可管理的分批方式通过 AI 模型流式传输数据，而无需一次性将所有数据加载到内存中，从而高效处理大型数据集。如需了解详情，请参阅 ai.classify 参考文档。
基于游标的 ai.classify 版本的函数签名如下所示：
CREATE OR REPLACE FUNCTION ai.classify(
input_cursor REFCURSOR,
categories TEXT[][],
examples TEXT DEFAULT NULL,
output_mode VARCHAR DEFAULT NULL,
batch_size INT DEFAULT NULL,
model_id VARCHAR(100) DEFAULT NULL)
RETURNS REFCURSOR
以下示例展示了如何使用游标向 ai.classify 提供输入：
DO $$
DECLARE
cur REFCURSOR;
result_cur REFCURSOR;
input_val TEXT;
sentiment TEXT;
BEGIN
OPEN cur FOR SELECT review FROM product_reviews ORDER BY id;
result_cur := ai.classify(
input_cursor => cur,
categories => ARRAY[
ARRAY['positive', 'Good sentiment'],
ARRAY['neutral', 'Neither good nor bad sentiment'],
ARRAY['negative', 'Bad sentiment']
],
batch_size => 20
);
LOOP
FETCH result_cur INTO input_val, sentiment;
EXIT WHEN NOT FOUND;
RAISE NOTICE 'Sentiment: %', sentiment;
END LOOP;
CLOSE result_cur;
CLOSE cur;
END $$;