云数据库 PostgreSQL 自动向量化

一、概述

tencentdb_ai 提供自动向量化（Auto Embedding）功能，允许用户在数据写入时自动完成文本到向量的转换，无需手动调用嵌入 API 或编写额外的 ETL 流程。只需一行 SQL 注册任务，后续对源表的所有 INSERT 和 UPDATE 操作都会自动触发向量生成，向量结果实时写回目标列，告别“数据写入 → 手动提取 → 调用嵌入 → 写回”的繁琐流程。

二、支持版本

数据库版本为 PostgreSQL 14 – 18，tencentdb_ai 扩展 ≥ 1.5（以实例中实际 extversion 为准）。

三、核心架构

自动向量化功能由三个核心组件协同工作：

四、适用场景

·RAG 知识库：文档分块入库后自动向量化，配合 tencentdb_ai.retrieve() / rag() 实现智能问答。

·商品搜索：商品描述/标题变更时自动更新向量索引，实现语义搜索。

·用户画像：用户行为文本实时向量化，支持相似用户推荐。

·内容审核：内容入库后自动向量化，配合相似度检索实现去重/审核。

五、前提条件

·数据库版本为 PostgreSQL 14-18，tencentdb_ai 扩展 ≥ 1.5（以实例中实际 extversion 为准）。

·pgvector 扩展（通过 tencentdb_ai CASCADE 自动安装）。

·pgmq 扩展（通过 tencentdb_ai CASCADE 自动安装）。

·已配置嵌入模型（如 kinfra-text-embedding-0.6b），并在 model_list 中设置 embedding_dim，配置方法请参见 tencentdb_ai 插件功能介绍。

·将 tencentdb_ai 加入 shared_preload_libraries 参数，以启用后台工作进程（修改后需重启实例生效）。

·配置 tencentdb_ai.autoembedding_database 指定工作数据库（修改后需重启实例生效）。

六、配置参数

在 postgresql.conf 中可配置以下 GUC 参数（均为 SIGHUP 级别，pg_reload_conf() 生效）：

八、一、add_incr_autoembedding_task() — 创建增量向量化任务

创建增量任务后，系统会自动为目标表添加 vector 类型的嵌入列，并创建 INSERT AFTER 和 UPDATE BEFORE 触发器。每当源列数据发生变化时，触发器自动将变更入队，后台工作进程异步处理。

九、函数签名

tencentdb_ai.add_incr_autoembedding_task( schema_name NAME, — 表所在 schema table_name NAME, — 表名 source_columns NAME[], — 源文本列名数组 model_name NAME, — 嵌入模型名称 target_column NAME DEFAULT NULL, — 目标向量列名 index_method TEXT DEFAULT 'hnsw', — 向量索引方法 options JSONB DEFAULT '{}' — 扩展选项) RETURNS BIGINT

十、参数说明

十一、前提条件

·调用者必须是表 owner 或 pg_tencentdb_superuser 角色。

·表必须有单列主键。

·源列必须存在（非文本类型列的值会被转为文本后参与向量化）。

·模型必须在 tencentdb_ai.model_list 中已注册。

·必须在配置的 autoembedding_database 中执行。

十二、行为说明

·向量由后台工作进程异步生成（默认约1秒轮询）：新写入或更新的行，其向量列会短暂为 NULL，随后自动写回。

·源列被 UPDATE 时，向量列会先被清空再异步重建（clear_embedding_on_update 选项，默认开启）。

·配置多源列时，按数组顺序将各列值以换行符拼接为一个输入文本（NULL 按空字符串处理）。

·任务存在期间，目标表及源列/目标列受保护：DROP TABLE 或 DROP COLUMN 会被阻止报错，需先删除任务。

十三、使用示例

— 单列嵌入：对 content 列创建嵌入，目标列自动命名为 content_embeddingSELECT tencentdb_ai.add_incr_autoembedding_task( 'public', 'articles', ARRAY['content'], 'kinfra-text-embedding-0.6b');– 多列嵌入：合并 title + body 生成嵌入，显式指定目标列和索引方法SELECT tencentdb_ai.add_incr_autoembedding_task( 'public', 'articles', ARRAY['title', 'body'], 'kinfra-text-embedding-0.6b', target_column => 'doc_embedding', index_method => 'hnsw');– 覆盖向量维度（当 model_list 中未设置 embedding_dim 时）SELECT tencentdb_ai.add_incr_autoembedding_task( 'public', 'articles', ARRAY['content'], 'kinfra-text-embedding-0.6b', options => '{"vector_dim": 1024}');

十四、二、add_backfill_autoembedding_task() — 创建存量向量化任务

存量任务用于对已有历史数据进行批量向量化回填。它不会创建新列或触发器，而是基于主键游标逐批扫描已有数据并入队。通常先创建增量任务（自动创建向量列），再创建存量任务回填历史数据。

十五、函数签名

tencentdb_ai.add_backfill_autoembedding_task( schema_name NAME, — 表所在 schema table_name NAME, — 表名 source_columns NAME[], — 源文本列名数组 model_name NAME, — 嵌入模型名称 target_column NAME DEFAULT NULL, — 目标向量列名 start_now BOOL DEFAULT false, — 是否立即开始回填 options JSONB DEFAULT '{}' — 扩展选项) RETURNS BIGINT

十六、参数说明

十七、前提条件

·目标向量列必须已存在（通常先由 add_incr_autoembedding_task 创建）。

·如果同一列已有增量任务，配置（source_columns model_name vector_dim）必须一致。

·必须在配置的 autoembedding_database 中执行。

十八、使用示例

— 先创建增量任务（自动创建向量列 + 触发器）SELECT tencentdb_ai.add_incr_autoembedding_task( 'public', 'articles', ARRAY['content'], 'kinfra-text-embedding-0.6b');– 再创建存量任务，立即回填历史数据SELECT tencentdb_ai.add_backfill_autoembedding_task( 'public', 'articles', ARRAY['content'], 'kinfra-text-embedding-0.6b', start_now => true);– 也可以先注册任务（默认 start_now 为 false），稍后手动触发SELECT tencentdb_ai.add_backfill_autoembedding_task( 'public', 'articles', ARRAY['content'], 'kinfra-text-embedding-0.6b');– 稍后手动启动SELECT tencentdb_ai.run_backfill_autoembedding_task(1);

十九、三、drop_incr_autoembedding_task() / drop_backfill_autoembedding_task() — 删除任务

删除任务时只清理元数据、触发器和队列中的待处理消息，不会删除已生成的向量列、索引或数据。

20、函数签名

tencentdb_ai.drop_incr_autoembedding_task(task_id BIGINT) RETURNS VOIDtencentdb_ai.drop_backfill_autoembedding_task(task_id BIGINT) RETURNS VOID

21、使用示例

— 删除增量任务SELECT tencentdb_ai.drop_incr_autoembedding_task(1);– 删除存量任务SELECT tencentdb_ai.drop_backfill_autoembedding_task(2);

22、四、run_backfill_autoembedding_task() — 手动触发存量回填

对于 start_now => false 创建的存量任务，或需要重新启动失败的任务，可以使用此函数手动触发。

23、函数签名

tencentdb_ai.run_backfill_autoembedding_task( task_id BIGINT, — 存量任务 ID batch_size INT DEFAULT 8192 — 后台工作进程每轮扫描入队的最大行数) RETURNS VOID

该函数仅将任务置为 running 状态并重置扫描游标，立即返回（无返回值）；实际扫描入队由后台工作进程按周期自动推进。任务已完成（done）时报错；任务失败（failed）时重置并重新开始。

24、使用示例

— 手动启动存量回填SELECT tencentdb_ai.run_backfill_autoembedding_task(1);

25、五、autoembedding_status — 任务状态视图

系统视图，实时展示所有自动向量化任务的状态。

26、视图列说明

27、使用示例

— 查看所有任务状态SELECT task_kind, task_id, schema_name, table_name, target_column, status, backfill_state, pending, backfilled_rows, failed_countFROM tencentdb_ai.autoembedding_statusORDER BY task_id;

28、六、autoembedding_error — 错误记录表

系统自动记录处理失败的详细信息，便于问题排查。

29、表列说明

30、使用示例

— 查看最近的错误SELECT task_kind, task_id, row_id, error_message, created_atFROM tencentdb_ai.autoembedding_errorORDER BY created_at DESCLIMIT 10;

31、完整使用示例

以下为你介绍一个端到端的完整示例，涵盖扩展安装、模型注册、增量任务创建、存量回填和数据验证：

32、步骤1：环境准备

— 安装扩展（pgmq / pgvector 通过 CASCADE 自动安装）CREATE EXTENSION IF NOT EXISTS tencentdb_ai CASCADE;– 注册嵌入模型（json_path 必须为 NULL）SELECT tencentdb_ai.add_model('kinfra-text-embedding-0.6b', NULL, NULL, NULL, 'tokenhub');SELECT tencentdb_ai.update_model_attr('kinfra-text-embedding-0.6b', 'api_key', 'your_api_key');– 设置嵌入维度（必须，否则创建任务时需通过 options.vector_dim 指定）UPDATE tencentdb_ai.model_list SET embedding_dim = 1024 WHERE model_name = 'kinfra-text-embedding-0.6b';

注意：说明：

注意：api_key 请在 TokenHub 控制台 获取。

33、步骤2：创建源表并写入数据

— 创建知识库表CREATE TABLE kb_articles ( id bigserial PRIMARY KEY, title text, content text);– 插入测试数据INSERT INTO kb_articles (title, content) VALUES ('PostgreSQL 简介', 'PostgreSQL 是一个功能强大的开源对象关系数据库系统…'), ('向量数据库', '向量数据库是一种专门用于存储和检索高维向量的数据库系统…'), ('RAG 技术', '检索增强生成（RAG）是一种结合检索和生成能力的 AI 技术…');

34、步骤3：创建自动向量化任务

— 创建增量任务：自动添加 content_embedding 列，创建触发器SELECT tencentdb_ai.add_incr_autoembedding_task( 'public', 'kb_articles', ARRAY['content'], 'kinfra-text-embedding-0.6b') AS incr_task_id;– 创建存量任务：立即回填已有的 3 行历史数据SELECT tencentdb_ai.add_backfill_autoembedding_task( 'public', 'kb_articles', ARRAY['content'], 'kinfra-text-embedding-0.6b', start_now => true) AS backfill_task_id;

35、步骤4：验证向量生成

— 等待后台进程处理（默认每 1 秒轮询一次）SELECT pg_sleep(3);– 检查存量回填进度SELECT backfill_state, backfilled_rowsFROM tencentdb_ai.autoembedding_statusWHERE task_kind = 'backfill';

backfill_state | backfilled_rows—————-+—————– done | 3(1 row)

— 验证向量已生成SELECT id, title, content_embedding IS NOT NULL AS has_embedding, vector_dims(content_embedding) AS dimsFROM kb_articlesORDER BY id;

id | title | has_embedding | dims—-+—————–+—————+—— 1 | PostgreSQL 简介 | t | 1024 2 | 向量数据库 | t | 1024 3 | RAG 技术 | t | 1024(3 rows)

— 查看任务状态SELECT * FROM tencentdb_ai.autoembedding_status;

36、步骤5：验证增量写入

— 插入新数据，触发器自动入队INSERT INTO kb_articles (title, content) VALUES ('嵌入模型', '嵌入模型是将文本转换为向量表示的机器学习模型…');– 等待后台进程处理SELECT pg_sleep(2);– 验证新数据向量已生成SELECT id, title, content_embedding IS NOT NULL AS has_embeddingFROM kb_articlesORDER BY id;

id | title | has_embedding—-+—————–+————— 1 | PostgreSQL 简介 | t 2 | 向量数据库 | t 3 | RAG 技术 | t 4 | 嵌入模型 | t(4 rows)

38、增量任务状态

注意：说明：

39、存量任务状态

41、常见错误场景

42、监控任务状态

— 检查队列积压SELECT task_kind, task_id, pendingFROM tencentdb_ai.autoembedding_statusWHERE pending > 0;– 查看错误详情SELECT * FROM tencentdb_ai.autoembedding_errorORDER BY created_at DESC LIMIT 20;

43、实践教程

1. 先增量后存量：先创建增量任务（自动创建向量列），再创建存量任务回填历史数据，确保新写入的数据不会遗漏。

2. 合理设置 batch_size：根据嵌入模型的 QPS 限制和单次最大输入 token 数，适当调整 autoembedding_batch_size。

3. 配置 embedding_dim：在 model_list 中设置 embedding_dim，避免每次创建任务时手动指定。

4. 监控错误表：定期检查 autoembedding_error 表，及时发现和处理失败的嵌入请求。

5. 控制存量回填速率：对于大表存量回填，可通过减小 batch_size 或增大 naptime_ms 控制速率，避免对在线业务造成影响。

6. 删除任务前先验证：drop_*_autoembedding_task 不删除向量列和数据，如需完全清理需手动 DROP COLUMN。

7. 大批量数据导入：大事务批量写入会逐行入队并触发模型调用，建议先完成数据导入，再创建增量任务并配套存量任务回填历史数据，避免导入过程产生大量队列积压。