tencent cloud

云数据库 PostgreSQL

文档云数据库 PostgreSQLAI 能力AI 大模型调用tencentdb_ai 插件功能介绍

tencentdb_ai 插件功能介绍

Download
聚焦模式
字号
最后更新时间： 2026-08-25 17:49:57
云数据库 PostgreSQL 提供 tencentdb_ai 插件，方便您在数据库实例中直接调用网络可通的大模型 API，完成对话、文本向量化（embedding）、RAG 检索增强生成、自动向量列维护（autoembedding）、自然语言生成 SQL（NL2SQL）等场景的应用开发。本插件支持大版本为 PostgreSQL 14 - 18 的实例。
说明：
使用 tencentdb_ai 的前提是您已经创建完成了大版本为 PostgreSQL 14 - 18 的实例。不同内核版本提供的插件版本不同，请以实例中 SELECT extversion FROM pg_extension WHERE extname = 'tencentdb_ai'; 的实际结果为准。本文以插件1.6版本为例介绍全部功能。
创建 tencentdb_ai 插件（1.6版本）会通过 CASCADE 关联创建 pgcrypto、vector（pgvector）、pgmq 三个插件，请知悉。
创建插件需要 tencentdb_superuser 权限。

模型后端说明

tencentdb_ai 通过 backend_type 区分模型后端，注册模型时指定。当前共支持三种后端：
后端
认证方式
状态
说明
tokenhub
Bearer api_key
推荐使用
大模型服务平台 TokenHub，OpenAI 兼容协议。支持对话（ChatCompletions）与文本向量化（GetEmbedding）两类接口。
hunyuan
SecretId/SecretKey（TC3 签名）
已弃用
混元大模型旧接入方式。存量实例可继续使用，新实例请使用 tokenhub，迁移方法请参见 tencentdb_ai 模型后端迁移指南。
lkeap
SecretId/SecretKey（TC3 签名）
已弃用
知识引擎原子能力旧接入方式（deepseek-v3、lke-text-embedding-v1、lke-reranker-base 等）。存量实例可继续使用，新实例请使用 tokenhub，迁移方法请参见 tencentdb_ai 模型后端迁移指南。
注册 tokenhub 后端的模型时：
通过 update_model_attr 配置模型级 api_key（加密存储），无需配置 SecretId/SecretKey。
网关偶发返回 HTTP 504（上游超时），重试即可；可通过 tencentdb_ai.http_timeout 调整 HTTP 超时。

支持的模型（tokenhub 后端）

插件通过 tokenhub 后端的对话与文本向量两类接口调用模型，支持情况如下：
类别
支持情况
对话模型
支持 TokenHub 平台的语言模型与多模态理解模型（限纯文本对话），如 hy3、glm-5.2、deepseek-v4-flash、deepseek-v4-pro、glm-5v-turbo 等，完整列表请参见 TokenHub 模型列表。
向量模型
kinfra-text-embedding-0.6b（1024维）、kinfra-text-embedding-4b（2560维）。
不支持
多模态向量模型（kinfra-vl-embedding-2b / 8b，调用协议与文本向量模型不同）、rerank 类模型（TokenHub 未提供）、图像 / 视频 / 3D / 语音生成类模型（插件无对应接口）。

tencentdb_ai 插件函数说明

新增模型

add_model 函数定义如下：
tencentdb_ai.add_model(
    p_model_name     NAME,
    p_version        TEXT,
    p_region         TEXT,
    p_json_path      JSONPATH,
    p_backend_type   TEXT DEFAULT 'hunyuan',
    p_real_model_name NAME DEFAULT NULL
);
参数解释如下：
p_model_name：模型名称（用户侧别名），如 hy3、glm-5.2、kinfra-text-embedding-0.6b 等。
p_version：该模型的公共参数 version，如该模型不需要 version 参数则可以不填写（tokenhub 后端不需要）。
p_region：该模型的公共参数 region，如该模型不需要 region 参数则可以不填写（tokenhub 后端不需要）。
p_json_path：指定如何对模型的 JSON 响应进行提取，相当于对模型输出调用 jsonb_path_query_first 函数。如果不指定该参数，默认原样输出模型的原始响应。tokenhub 聊天模型建议设为 '$.choices[0].message.content'；通过 get_embedding 调用的 embedding 模型（不限后端）必须设为 NULL，否则 call_model 会先按 json_path 提取响应，get_embedding 将无法解析。
p_backend_type：模型后端类型，取值为 tokenhub、hunyuan、lkeap。
p_real_model_name：发送给后端 API 的真实模型名。不填写时默认与 p_model_name 相同。不同后端可托管同一底层模型，因此允许用别名对外、真实名对内。
说明：
向量维度（embedding_dim）不是 add_model 的参数。该维度契约供 autoembedding 使用，可由 tencentdb_superuser 执行 UPDATE tencentdb_ai.model_list SET embedding_dim = <维度> WHERE model_name = '<模型名>'; 设置，或在注册 autoembedding 任务时通过 options.vector_dim 指定。

查看已注册模型

list_models 函数定义如下：
tencentdb_ai.list_models(void);
返回 tencentdb_ai.model_list 集合，包含 model_name、json_path、backend_type、real_model_name、embedding_dim、version、region 等列。SecretId/SecretKey/api_key 加密存储，id_random、key_random、api_key_random 为加密随机数，无需关注。

更新模型

update_model_attr 函数定义如下：
tencentdb_ai.update_model_attr(
    model_name NAME,
    attr_name  TEXT,
    attr_value TEXT
);
参数解释如下：
model_name：模型名称。
attr_name：需要更新的模型属性。常用属性有 version、region、json_path、SecretId、SecretKey、api_key、backend_type、real_model_name。其中 SecretId、SecretKey、api_key 会加密后存储。model_name、id_random、key_random、api_key_random 不允许修改。
attr_value：需要更新的属性的值。

删除模型

delete_model 函数定义如下：
tencentdb_ai.delete_model(
    model_name NAME
);
参数解释如下：
model_name：模型名称。模型不存在时报错。

模型调用

call_model 函数定义如下：
tencentdb_ai.call_model(
    model_name    NAME,
    common_params TEXT[],
    api_params    TEXT[]
);
参数解释如下：
model_name：模型名称。
common_params：调用模型的公共参数，例如 hunyuan 后端的 ARRAY['Action: ChatCompletions', 'Version: 2023-09-01']。tokenhub 后端聊天传空数组，向量化传 ARRAY['Action: GetEmbedding']，其余 Action 不支持。
api_params：调用模型的专有参数。tokenhub 后端聊天示例：ARRAY['"model": "glm-5.2"', '"messages": [{"role": "user", "content": "您好"}]', '"stream": false']，注意 "model" 字段需自行传入，call_model 不会自动补充。
call_model 是模型调用的最底层函数，下文的固定场景接口均基于它封装（chat_completions 等会自动补充 "model" 字段）。推荐使用固定场景接口进行模型调用，仅在没有合适的场景接口时才直接使用 call_model。
调用示例：
postgres=> SELECT tencentdb_ai.call_model('glm-5.2', ARRAY[]::TEXT[],
                  ARRAY['"model": "glm-5.2"', '"messages": [{"role": "user", "content": "用一句话介绍 PostgreSQL"}]', '"stream": false']);
                                                         raw_response
-----------------------------------------------------------------------------------------------------------------------------------
 "PostgreSQL 是一款功能强大的开源对象关系型数据库，以其卓越的稳定性、高度的可扩展性以及对复杂查询和丰富数据类型的完美支持而闻名。"
(1 row)

固定场景接口

对话

chat_completions 函数定义如下：
tencentdb_ai.chat_completions(
    model_name NAME,
    content    TEXT,
    args       TEXT[] DEFAULT NULL
);
参数解释如下：
model_name：模型名称。
content：对话内容。
args：调用模型的其他参数，默认为 NULL。
调用示例（tokenhub 后端，下同）：
postgres=> SELECT tencentdb_ai.chat_completions('glm-5.2', '你好，请用一句话介绍你自己');
                                              glm_answer
----------------------------------------------------------------------------------------------------------
 "我是Z.ai训练的GLM大语言模型，能够回答问题、提供信息并与用户进行各类对话交流。"
(1 row)
说明：
若模型注册时指定了 json_path（如 '$.choices[0].message.content'），返回值为提取后的 JSON 字符串文本（两侧带双引号）；json_path 为 NULL 时返回模型原始响应。

文本转向量

get_embedding 函数定义如下：
tencentdb_ai.get_embedding(
    model_name NAME,
    content    TEXT[]
);
参数解释如下：
model_name：模型名称。
content：转化内容（数组，可批量）。返回 SETOF FLOAT8[][]，每个输入对应一行向量。
调用示例：
postgres=> SELECT array_length(e, 1) AS dim FROM tencentdb_ai.get_embedding('kinfra-text-embedding-0.6b', ARRAY['PostgreSQL 是一个开源关系型数据库']) AS e;
 dim
------
 1024
(1 row)

文本排序

run_rerank 函数定义如下：
tencentdb_ai.run_rerank(
    model_name NAME,
    query      TEXT,
    documents  TEXT[],
    args       TEXT[] DEFAULT NULL
);
参数解释如下：
model_name：模型名称。
query：文本排序的问题。
documents：待文本排序的内容。
args：特定模型的指定参数。
说明：
run_rerank 仅支持 lkeap 后端模型（如 lke-reranker-base）。lkeap 后端已弃用；tokenhub 后端仅支持 ChatCompletions 与 GetEmbedding 两类接口，调用其他 Action 会被拒绝。

图生文

image_to_text 函数定义如下：
tencentdb_ai.image_to_text(
    model_name NAME,
    query      TEXT,
    image      TEXT,
    args       TEXT[] DEFAULT NULL
);
参数解释如下：
model_name：模型名称。
query：图生文本的问题。
image：图片地址。
args：特定模型的指定参数。
说明：
image_to_text 按 hunyuan 后端的多模态报文格式构造请求，仅支持 hunyuan 后端的视觉模型。hunyuan 后端已弃用；tokenhub 后端暂不支持该接口（会返回网关参数错误）。

情感分析与摘要

sentiment、summarize 函数定义如下：
tencentdb_ai.sentiment(
    model_name NAME,
    content    TEXT,
    args       TEXT[] DEFAULT NULL
);

tencentdb_ai.summarize(
    model_name NAME,
    content    TEXT,
    args       TEXT[] DEFAULT NULL
);
参数解释如下：
model_name：模型名称。
content：待分析的文本。
args：调用模型的其他参数，默认为 NULL。
sentiment 以一词返回情感倾向（positive / negative / neutral / mixed），summarize 返回文本摘要。调用示例：
postgres=> SELECT tencentdb_ai.sentiment('hy3', '今天天气真好，我特别开心');
 sentiment
------------
 "positive"
(1 row)

postgres=> SELECT tencentdb_ai.summarize('hy3', 'PostgreSQL 是一个功能强大的开源对象关系数据库系统，拥有超过30年的开发历史，在可靠性、功能稳健性和性能方面赢得了良好声誉。');
                                                summarize
----------------------------------------------------------------------------------------------------------
 "PostgreSQL 是一款开源的对象关系型数据库系统，有 30 多年开发历史，以可靠性、功能稳健和性能优异著称。"
(1 row)

文本生成

generate_text、generate_int、generate_double、generate_boolean 函数定义如下：
tencentdb_ai.generate_text(model_name NAME, prompt TEXT, args TEXT[] DEFAULT NULL);
tencentdb_ai.generate_int(model_name NAME, prompt TEXT, args TEXT[] DEFAULT NULL);
tencentdb_ai.generate_double(model_name NAME, prompt TEXT, args TEXT[] DEFAULT NULL);
tencentdb_ai.generate_boolean(model_name NAME, prompt TEXT, args TEXT[] DEFAULT NULL);
参数解释如下：
model_name：模型名称。
prompt：生成提示词。
args：调用模型的其他参数，默认为 NULL。
四个函数分别约束模型只返回文本、整数、数值、布尔值（true/false）。返回值均为 TEXT 类型，可按需强制转换。调用示例：
postgres=> SELECT tencentdb_ai.generate_int('hy3', '一百二十三加四百五十六等于多少');
 gen_int
---------
 "579"
(1 row)

postgres=> SELECT tencentdb_ai.generate_boolean('hy3', 'PostgreSQL 是关系型数据库吗');
 gen_bool
----------
 "true"
(1 row)

NL2SQL：自然语言生成 SQL

generate_query 自动收集当前库的 schema 信息作为上下文，调用大模型生成 SQL。
generate_query 函数定义如下：
tencentdb_ai.generate_query(
    model_name NAME,
    nl_query   TEXT,
    args       TEXT[] DEFAULT NULL
);
参数解释如下：
model_name：模型名称。
nl_query：自然语言查询需求。建议在问题中包含目标表的表名，以便插件为该表生成列级 schema 上下文，显著提高生成准确率。
args：调用模型的其他参数，默认为 NULL。
调用示例：
postgres=> SELECT tencentdb_ai.generate_query('hy3', '查询 users 表中年龄最大的用户姓名');
                        nl2sql
---------------------------------------------------------------
 SELECT u.name FROM public.users u ORDER BY u.age DESC LIMIT 1
(1 row)
生成的 SQL 默认带 LIMIT 1000 保护（除非显式要求全量），并禁止访问 information_schema 与 pg_catalog。
辅助函数（供 generate_query 内部使用，也可单独调用做 schema 探查）：
tencentdb_ai.get_database_tables()：列出所有用户表及估算行数。
tencentdb_ai.get_table_details(p_table_name TEXT, p_schema_name TEXT DEFAULT 'public')：返回表字段、类型、约束、主外键等信息。
tencentdb_ai.get_table_indexes(p_table_name TEXT, p_schema_name TEXT DEFAULT 'public')：返回表的索引定义。

RAG：检索增强生成

tencentdb_ai 提供 RAG（Retrieval-Augmented Generation，检索增强生成）能力，依赖 pgvector 插件，可在数据库内直接完成“向量检索 → 构建提示词 → 大模型生成”的完整链路，核心接口为 tencentdb_ai.retrieve 与 tencentdb_ai.rag。详细说明请参见 tencentdb_ai RAG。

Autoembedding：自动向量列维护

tencentdb_ai 提供 autoembedding 自动向量列维护能力：注册任务后，业务表写入/更新源文本列时由后台 worker 自动调用 embedding 模型生成向量并写回，无需应用层参与。详细说明请参见 自动向量化。

插件使用示例

下面以 tokenhub 后端为例，描述插件的完整使用过程：
1. 创建插件（会关联创建 pgcrypto、vector、pgmq 插件）
postgres=> CREATE EXTENSION tencentdb_ai CASCADE;
NOTICE:  installing required extension "pgcrypto"
NOTICE:  installing required extension "vector"
NOTICE:  installing required extension "pgmq"
CREATE EXTENSION
2. 注册模型并配置 api_key（api_key 请在 TokenHub 控制台 获取；embedding 模型的 json_path 必须为 NULL）。
postgres=> SELECT tencentdb_ai.add_model('glm-5.2', NULL, NULL, '$.choices[0].message.content'::jsonpath, 'tokenhub');
postgres=> SELECT tencentdb_ai.update_model_attr('glm-5.2', 'api_key', 'sk-********');
postgres=> SELECT tencentdb_ai.add_model('kinfra-text-embedding-0.6b', NULL, NULL, NULL, 'tokenhub');
postgres=> SELECT tencentdb_ai.update_model_attr('kinfra-text-embedding-0.6b', 'api_key', 'sk-********');
3. 对话调用。
postgres=> SELECT tencentdb_ai.chat_completions('glm-5.2', '你好，请用一句话介绍你自己') AS answer;
                                              answer
----------------------------------------------------------------------------------------------------------
 "我是Z.ai训练的GLM大语言模型，能够回答问题、提供信息并与用户进行各类对话交流。"
(1 row)
4. 文本向量化调用。
get_embedding 返回 SETOF FLOAT8[][]，每个输入文本对应一行向量。下面的示例统计返回向量的维度：
postgres=> SELECT array_length(e, 1) AS dim
           FROM tencentdb_ai.get_embedding('kinfra-text-embedding-0.6b',
                                           ARRAY['PostgreSQL 是一个开源关系型数据库']) AS e;
 dim
------
 1024
(1 row)
返回的向量可直接存入 pgvector 的 vector 类型列，用于相似度检索、RAG 等场景。更多场景示例（RAG、自动向量列、NL2SQL 应用构建）请参见 使用 tencentdb_ai 调用大模型构建应用 与 tencentdb_ai RAG。
上一篇: 自动向量化下一篇: 使用 tencentdb_ai 调用大模型构建应用

帮助和支持

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

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

文档反馈