tencent cloud

云数据库 PostgreSQL

文档云数据库 PostgreSQLAI 能力AI 大模型调用tencentdb_ai 模型后端迁移指南

tencentdb_ai 模型后端迁移指南

Download
聚焦模式
字号
最后更新时间： 2026-08-20 17:45:11
本文档已由 AI 辅助审校

背景

原混元大模型、知识引擎原子能力 DeepSeek API 已不再新增模型能力，并停止新购模型服务，后续所有能力将迁移到大模型服务平台 TokenHub（已购服务在停服前可继续使用，具体停服时间以平台下线公告为准，请参见 TokenHub 平台迁移文档）。
tencentdb_ai 插件的 hunyuan、lkeap 模型后端随平台同步弃用，推荐您将在用模型迁移到 tokenhub 后端。本文介绍迁移方法。

迁移概览

后端差异对照

项目
hunyuan / lkeap 后端（已弃用）
tokenhub 后端（推荐）
认证方式
SecretId / SecretKey（TC3 签名）
api_key（Bearer）
响应协议
腾讯云 API 格式（$.Response...）
OpenAI 兼容格式（$.choices...、$.data...）
version / region
需要（如 2023-09-01、ap-guangzhou）
不需要，注册时传 NULL
模型名
注册名即调用名
model_name 仅是插件内的别名；插件实际发给 TokenHub 网关的模型标识由 real_model_name 决定，必须填写控制台“在线推理”中已开通模型的服务 ID（如 hy3），否则报 The model or service ID xxx does not exist

功能影响一览

插件功能
hunyuan / lkeap
tokenhub
迁移动作
对话 chat_completions
✓
✓
仅配置变更
固定场景（sentiment / summarize / generate_text / generate_int / generate_double / generate_boolean）
✓
✓
仅配置变更
NL2SQL（generate_query）
✓
✓
仅配置变更
文本向量 get_embedding
✓
✓
配置变更 + 存量数据重新 embedding
RAG（retrieve / rag）
✓
✓
配置变更 + 存量数据重新 embedding
自动向量列 autoembedding
✓
✓
任务重建 + 存量数据重新 embedding
文本排序 run_rerank
✓（仅 lkeap）
×
无迁移路径，请用向量检索排序替代

准备工作

开通 TokenHub 服务并创建 API Key

1. 登录 TokenHub 控制台，开通需要使用的模型服务。
2. 在 API Key 管理 创建 API Key（sk- 开头）。原平台的 SecretId/SecretKey 与 API Key 不通用，必须重新创建。

选择新模型

TokenHub 可用模型的完整列表与规格请参见 TokenHub 模型列表，请按业务需要自行选择。常用类型速览：
类型
模型（服务 ID）
关键规格
语言模型
hy3、glm-5.2、deepseek-v4-flash、deepseek-v4-pro、kimi-k2.7、minimax-m3 等
上下文256k - 1M，详见模型列表
向量模型
kinfra-text-embedding-0.6b
1024维，32k 上下文，轻量低成本
向量模型
kinfra-text-embedding-4b
2560维，32k 上下文，高质量检索
说明：
TokenHub 平台上的多模态向量模型（kinfra-vl-embedding-2b / 8b）调用协议与文本向量模型不同，插件的 get_embedding 无法调用，请勿注册使用。
平台偶发返回 HTTP 504（上游超时），重试即可。

插件配置差异三要点

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');   -- 换成你选择的服务 ID
SELECT 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_count
FROM 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, distance
FROM tencentdb_ai.retrieve(
    'kinfra-text-embedding-0.6b', '你的查询',
    'public', 'kb_docs', 'chunk', 'embedding', 10, 'cosine'
)
ORDER BY distance, chunk;
上一篇: tencentdb_ai RAG下一篇: pgvectorscale（DiskANN）高性能向量检索

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈