云数据库 PostgreSQL tencentdb_ai 模型后端迁移指南

一、背景

tencentdb_ai 插件的 hunyuan、lkeap 模型后端随平台同步弃用，推荐你将在用模型迁移到 tokenhub 后端。这篇说说迁移方法。

二、后端差异对照

三、功能影响一览

四、开通 TokenHub 服务并创建 API Key

1. 登录 TokenHub 控制台，开通需要使用的模型服务。

2. 在 API Key 管理 创建 API Key（sk- 开头）。原平台的 SecretId/SecretKey 与 API Key 不通用，必须重新创建。

五、选择新模型

TokenHub 可用模型的完整列表与规格请参见 TokenHub 模型列表，请按业务需要自行选择。常用类型速览：

注意：说明：

六、插件配置差异三要点

1. 认证：用 api_key 取代 SecretId / SecretKey：

SELECT tencentdb_ai.update_model_attr('<模型名>', 'api_key', 'sk-********');

2. json_path：对话模型由混元格式 '$.Response.Choices[*].Message.Content' 改为 OpenAI 格式 '$.choices[0].message.content'；embedding 模型始终为 NULL（由 get_embedding 自行解析响应）。

3. version / region：tokenhub 后端不需要，注册新模型时传 NULL。已注册模型上残留的旧 version / region 值对 tokenhub 后端不生效，无需清理。

七、对话类功能迁移

涉及功能：chat_completions、sentiment、summarize、generate_text、generate_int、generate_double、generate_boolean、generate_query。

对话调用是无状态的，只需更新模型注册信息，业务 SQL 无需改动。推荐原地更新方式（模型名保持不变）：

— 以旧模型 my-chat（原 hunyuan 后端）为例，依次更新四项属性SELECT tencentdb_ai.update_model_attr('my-chat', 'backend_type', 'tokenhub');SELECT tencentdb_ai.update_model_attr('my-chat', 'real_model_name', 'hy3'); — 换成你选择的服务 IDSELECT tencentdb_ai.update_model_attr('my-chat', 'json_path', '$.choices[0].message.content');SELECT tencentdb_ai.update_model_attr('my-chat', 'api_key', 'sk-********');– 验证：业务 SQL 模型名不变，直接可用SELECT tencentdb_ai.chat_completions('my-chat', '你好，一句话介绍你自己');

answer————————————————————————————– "你好，我是混元，是由腾讯开发的大模型，能为你解答问题、提供信息并协助处理各类任务。"(1 row)

如果你希望保留旧配置对照验证，也可以另行注册新模型（路径 B），再将业务 SQL 中的模型名逐个替换：

SELECT tencentdb_ai.add_model('hy3', NULL, NULL, '$.choices[0].message.content'::jsonpath, 'tokenhub');SELECT tencentdb_ai.update_model_attr('hy3', 'api_key', 'sk-********');

八、embedding 类功能迁移

涉及功能：get_embedding，以及依赖它的 retrieve、rag、autoembedding。

注意：更换 embedding 模型即更换向量空间。即使新旧模型维度相同，旧模型生成的向量也无法与新模型生成的向量比较，存量知识库中的向量数据必须全部用新模型重新 embedding，否则检索结果错乱。

九、步骤一：注册新 embedding 模型

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', 'sk-********');

十、步骤二：重嵌存量数据

新旧模型维度相同（如 hunyuan-embedding 1024 维 → kinfra-text-embedding-0.6b 1024 维）时，列定义不变，直接更新：

UPDATE kb_docs SET embedding = ( SELECT e::vector(1024) FROM tencentdb_ai.get_embedding('kinfra-text-embedding-0.6b', ARRAY[chunk]) AS e);

数据量较大时建议按主键范围分批执行，避免单批超时或触发平台限流。

新旧模型维度不同（如改用 kinfra-text-embedding-4b 2560 维）时，需先清空向量列、修改列维度后再重嵌：

UPDATE kb_docs SET embedding = NULL;ALTER TABLE kb_docs ALTER COLUMN embedding TYPE vector(2560);UPDATE kb_docs SET embedding = ( SELECT e::vector(2560) FROM tencentdb_ai.get_embedding('kinfra-text-embedding-4b', ARRAY[chunk]) AS e);

重嵌完成后，如向量列上建有 ivfflat / hnsw 索引，建议重建索引以保证召回质量：

REINDEX INDEX <索引名>;

十一、步骤三：autoembedding 用户重建任务

使用了自动向量列维护的表，需按以下流程重建任务并重嵌：

— 1. 删除旧任务（任务 ID 可通过 tencentdb_ai.autoembedding_status 视图查询）SELECT tencentdb_ai.drop_incr_autoembedding_task(<旧任务ID>);– 2. 清空旧向量（若同时更换了模型注册，先完成 update_model_attr）UPDATE notes SET body_embedding = NULL;– 3. 重新注册增量任务SELECT tencentdb_ai.add_incr_autoembedding_task('public', 'notes', ARRAY['body']::name[], 'kinfra-text-embedding-0.6b');– 4. 注册回填任务，重嵌存量数据SELECT tencentdb_ai.add_backfill_autoembedding_task('public', 'notes', ARRAY['body']::name[], 'kinfra-text-embedding-0.6b', NULL, true);– 5. 查看回填进度SELECT task_kind, status, backfill_state, backfilled_rows, failed_countFROM tencentdb_ai.autoembedding_status;

task_kind | status | backfill_state | backfilled_rows | failed_count———–+———+—————-+—————–+————– incr | enabled | | | 0 backfill | | done | 2 | 0(2 rows)

十二、run_rerank 迁移说明

TokenHub 当前不提供 rerank 模型，插件的 run_rerank 仅支持 lkeap 后端，无迁移路径。建议使用向量检索按距离排序替代：

SELECT chunk, distanceFROM tencentdb_ai.retrieve( 'kinfra-text-embedding-0.6b', '你的查询', 'public', 'kb_docs', 'chunk', 'embedding', 10, 'cosine')ORDER BY distance, chunk;