文档中心

AI 原生 BaaS 平台 Supabase 版

插件

AI（rds_ai）

rds_ai 插件提供数据库侧 AI 调用能力。你可以通过 ai_query、ai_embed、ai_rank、ai_retrieve 和 ai_rag完成对话生成、文本向量化、文档重排序、向量检索和检索增强生成。插件还提供模型管理、API Key 管理、代理配置、Token 限流和接口调用统计等能力。

核心能力：通过 SQL 函数（ai_query、ai_embed、ai_rank、ai_retrieve 和 ai_rag）在数据库侧直接访问和使用大模型，覆盖对话生成、文本向量化、文档重排序、向量检索和检索增强生成（RAG）等场景。

解决问题：在数据库中直接处理和分析非结构化数据，简化传统“数据出库-模型处理-结果入库”的复杂流程。

前提条件

在开始之前，请确保满足以下条件：

已安装 pgcrypto 插件（rds_ai 依赖此插件进行加密操作，pgcrypto 支持动态加载）。

将 rds_ai 加入到 shared_preload_libraries 参数中。

如您需要使用 1.3 版本的 rds_ai 插件，则需要先安装 pgvector 插件。详细信息，请参见安装 pgvector。

角色与权限边界

平台管理员负责启用扩展、安装依赖、设置实例级白名单和平台策略。

高权限数据库角色负责模型、API Key、默认模型、统计和限流管理。

普通应用用户可调用公开 AI 函数，但 ai_retrieve 和 ai_rag 均以 SECURITY INVOKER 运行，会按调用者身份检查来源表及相关列的 SELECT 权限，且行级安全策略（RLS）继续生效。

注意

不要在 SQL、日志、工单或截图中暴露真实 API Key、代理密码或生产 rds.ai_meta_json。实例迁移或恢复后，加密密钥来源可能变化，应重新设置 API Key 和代理密码。

配置 API 密钥

配置全局 API Key

为了让插件能够访问 AI 模型服务，你需要配置一个全局的 API Key。该 Key 为火山方舟（Volcano Ark）的 API Key，用于调用方舟上的豆包对话模型、向量模型等服务，可在火山方舟控制台创建和获取。此密钥将被加密存储在数据库中。此密钥将被加密存储在数据库中。

注意

set_apikey 函数的第一个参数 key_name 当前版本暂未使用，但为必填项，可填入任意描述性名称。

一个数据库内只支持配置一个全局 API Key。SET LOCAL rds.ai_rag_query_rewrite = off;

当实例通过迁移或恢复功能重建后，旧的加密 API Key 会失效，你需要重新执行此命令进行设置。

get_apikey() 仅返回 key_name，出于安全考虑，不返回明文或加密后的 API Key。

配置 Rerank 专用 API Key（1.3 及以后版本支持）

1.3 版本新增了重排序（rerank）模型专用的 API Key。rds_ai 插件的重排序（rerank）能力基于火山引擎 ContextSearch 提供的 rerank 模型服务，当前预置模型为通义千问 qwen3-reranker-0.6b。

核心功能与操作

本章节介绍如何使用 rds_ai 插件管理 AI 模型、调用核心 AI 功能以及监控使用情况。

模型管理

在使用 AI 功能前，你需要先将模型的信息添加到插件中。

添加模型

使用 rds_ai.add_model 函数来注册一个新的 AI 模型。你需要提供模型的服务地址、请求体模板等关键信息。

参数	说明
model_id	模型的唯一标识符（ID），例如火山方舟服务的 Endpoint ID。必选参数。
model_name	模型的调用名称，在 ai_query、ai_embed 和 ai_rank 函数中使用。必选参数。
model_url	模型服务的 HTTP 请求地址。必选参数。
model_type	取值为 chat、llm、embedding 或 rank，分别对应对话模型、大语言模型、向量模型和重排序模型。必选参数。
body_template	发起 HTTP 请求时，请求体的 JSON 格式模板。使用 %s 作为占位符，分别代表 model_name 和用户输入。必选参数。
result_path	一个 SQL SELECT 语句，用于从模型返回的 JSON 响应中提取核心结果。%L 会被替换为原始的 JSON 响应。如果为空，则返回完整的 JSON 响应。可选参数。
token_path	一个 SQL SELECT 语句，用于从模型返回的 JSON 响应中提取 Token 消耗数量。%L 会被替换为原始的 JSON 响应。如果为空，则不统计 Token 消耗。可选参数。

示例：添加一个文本向量化（Embedding）模型

示例：添加一个对话（Chat）模型

此示例中：

body_template 定义了请求体，其中第一个 %s 将被替换为模型名称 'Doubao-embedding-large'，第二个 %s 将被替换为用户调用 ai_embed 时传入的文本。

result_path 定义了如何从返回的 JSON 中解析出向量数据。

token_path 定义了如何从返回的 JSON 中解析出消耗的 Token 数量。

列出已添加的模型

使用 rds_ai.list_model 函数可以查看当前数据库中已注册的所有模型及其配置信息，包括平台预置模型和用户自定义模型。

删除模型

如果你不再需要某个模型，可以使用 rds_ai.remove_model 函数将其删除。

设置默认模型

你可以为 ai_query、ai_embed 和 ai_rank 函数分别设置一个默认模型。当用户调用这些函数但未指定模型名称时，将自动使用默认模型。

查看默认模型（1.3 及以后版本支持）

使用 rds_ai.get_default_model() 可以查看 ai_query、ai_embed 和 ai_rank 当前配置的默认模型。

预置模型

全新安装 1.3 版本时会自动注册以下预置模型（仅当 model_name 和 model_id 均未被占用时才注册，不覆盖用户已有模型）：

模型名（model_name）	类型	说明	API 端点
doubao-seed-2-1-turbo-260628	chat	豆包对话模型（chat/completions API）	https://ark.cn-beijing.volces.com/api/v3/chat/completions
doubao-seed-2-1-pro-260628	chat	豆包对话模型（Responses API）	https://ark.cn-beijing.volces.com/api/v3/responses
doubao-embedding-vision-251215	embedding	豆包多模态向量模型	https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal
qwen3-reranker-0.6b	rank	通义千问重排序模型	https://ai-inference-cn-beijing.contextsearch.volces.com/.../v1/rerank

AI 功能调用

配置好模型后，你可以使用 ai_query 和 ai_embed 函数与 AI 模型进行交互。1.3 版本还新增了 ai_rank、ai_retrieve 和 ai_rag 函数，支持文档重排序、向量检索和检索增强生成（RAG）。

智能问答

使用 rds_ai.ai_query 函数向指定的对话模型提问。

用法

content / input：用户输入文本。

model_name：你要使用的模型名称。可选参数，如果留空，将使用为 ai_query 设置的默认模型。不能传 embedding 或 rank 模型。

body_extra：JSON object 字符串，默认为 {}。用于向请求体追加额外参数，与模型自身的 body_template 合并，同名字段以调用级值为准。例如可通过 body_extra 显式设置 thinking。

header_extra：JSON object 字符串，默认为 {}。用于向请求头追加额外的 HTTP 头。

示例

文本向量化

使用 rds_ai.ai_embed 函数将文本转换为向量（float[] 数组），常用于构建向量索引和实现语义搜索。

用法

content / input：待向量化文本。

model_name：你要使用的 Embedding 模型名称。可选参数，如果留空，将使用为 ai_embed 设置的默认模型。不能传 chat 或 rank 模型。

body_extra：JSON object 字符串，默认为 {}。可通过 body_extra 传入 dimensions 等模型请求参数。

header_extra：JSON object 字符串，默认为 {}。

示例

说明

ai_embed 函数返回的是向量文本表示（text 类型），而不是 PostgreSQL 数组类型。为了进行高效的相似度搜索，建议将此结果显式转换为 vector、halfvec 或 sparsevec 类型并存储在 vector 类型的列中，创建相应的向量索引（如 HNSW 索引）。向量表示和维度必须与目标列一致。

文档重排序（ai_rank）

使用 rds_ai.ai_rank 函数按问题相关性对候选文本重新排序。该函数以 SECURITY DEFINER 运行，返回 TABLE(score_value, text_value)，按相关性从高到低排列。

用法

query：查询文本。

document：待排序的文档数组（text[] 类型）。

args：JSON object，可选，默认 {}。只支持 top_n（正整数）和 instruct（字符串）。

model_name：可选，默认为 NULL；为 NULL 时使用 ai_rank 默认模型。

示例

向量检索（ai_retrieve）

使用 rds_ai.ai_retrieve 将问题向量化后，在指定表的向量列上执行相似度检索，返回 TopN 文本块及距离值。该函数以 SECURITY INVOKER 运行，调用者必须具备来源表及相关列的 SELECT 权限，RLS 继续生效。

用法

distance_type 支持 cosine、l2、l1、negative 四种；l1 要求 pgvector 0.7.0 或更高版本。

embed_model 为 NULL 时使用 ai_embed 默认模型。

示例

检索增强生成（ai_rag）

rds_ai.ai_rag 实现端到端 RAG 流程：问题改写（可选）→ 向量检索 → 重排序（可选）→ 动态截断（仅 rerank 路径）→ 条件式 U-Shape 排列 → 构建 Prompt → LLM 生成回答。该函数以 SECURITY INVOKER 运行，调用者必须对知识库来源表及相关列具备 SELECT 权限，RLS 继续生效。

用法

prompt_model 为 NULL 时使用 ai_query 默认模型。

rank_model 为 NULL 时解析 ai_rank 默认模型；两者都没有时发出 WARNING 并跳过 rerank。

示例

配置超时时间

AI 模型的调用可能耗时较长。你可以通过 GUC 参数调整网络连接和请求处理的超时时间。

rds.ai_connect_timeout_msec：建立 HTTP 连接的超时时间，单位为毫秒。默认为 1000 （1 秒）。0 表示一直等待。

rds.ai_timeout_msec：等待模型处理并返回结果的超时时间，单位为毫秒。默认为 5000 （5 秒）。0 表示一直等待，应谨慎使用。

示例：在当前会话中将处理超时时间延长到 30 秒

注意

使用 ai_query 时，超时是一个常见问题。请根据你的具体业务场景和网络环境，通过测试找到一个合适的超时时间。如果频繁遇到超时错误，应适当调高 rds.ai_timeout_msec 的值。

配置域名白名单

通过 rds.ai_domain_allowlist GUC 参数限制插件可访问的模型 URL 域名。使用逗号分隔，只有白名单中的域名，插件才会发起 HTTP 请求。该参数为 PGC_SUSET 级别，需超级用户设置。

统计与监控

rds_ai 插件提供了一些函数来帮助你监控模型的使用情况和 Token 消耗。

查看模型调用统计

使用 rds_ai.rds_ai_stat 视图可以查看每个模型的调用次数、失败次数和累计消耗的 Token。

返回字段说明:

model_name：模型名称。

total_tokens：累计消耗的 Token 数量。

total_calls：累计调用次数。

total_fails：累计失败次数。

说明

model_name 当前最大支持 95 个字节，超过长度会被截断。统计信息最大支持的模型数量默认为 64 个（约 10KB 内存），可通过 rds.ai_max_model_num GUC 调节（需重启）。当调用的模型不存在时，不会记录在统计信息中，以防止 hash 表膨胀。

查看详细调用统计（1.3 及以后版本支持）

rds_ai_stat_detail() 区分模型内部调用和顶层接口调用。内部模型调用按 ai_query、ai_embed、rank 等接口和具体模型记录；顶层 ai_retrieve、ai_rag 也单独记录接口调用（此类记录的 model_name 为空）。返回列为 interface_name, model_name, total_tokens, total_calls, total_fails, stats_reset。

重置调用统计

如果需要清空当前的累计统计数据，可以执行以下命令：

查询周期 Token 消耗

你可以查询当天或当月至今的 Token 总消耗量。

高级配置

设置模型响应大小限制

为了防止因模型返回过大的响应而消耗过多内存，你可以为特定模型设置响应内容的最大字节数。

如果响应超过此限制，调用将报错，从而避免潜在的内存溢出问题。

配置 HTTP 代理（1.3 及以后版本支持）

当网络路径要求通过代理访问模型服务时，可以配置 HTTP 代理。代理密码会加密保存，查询时不返回密码。

配置并发请求限制（1.3 及以后版本支持）

通过 rds.ai_max_concurrent_requests GUC 参数控制最大并发 HTTP 请求数。0 表示不限制（默认值）；超过限制时请求会排队等待。该参数为 PGC_SIGHUP 级别，修改后需 reload 配置。

配置 RAG 行为（1.3 及以后版本支持）

GUC 参数	说明
rds.ai_rag_query_rewrite	是否开启 RAG query 改写。开启后先调用 LLM 将用户问题改写为独立的搜索 query 再进行向量检索。默认 false。
rds.ai_rag_dynamic_truncate_topn	是否开启动态截断。仅在 rerank 路径生效：若相邻分差占总降幅 80% 以上，则截断低分尾部并至少保留前 5 条。默认 true。
rds.ai_rag_ushape_char_threshold	U-Shape 排列的字符阈值。仅当已启用 rerank 且上下文总字符数达到该阈值时，将最高分片段放在开头、次高分放在结尾。默认 32768。

配置全局额外 HTTP 参数（1.3 及以后版本支持）

GUC 参数	说明
rds.ai_extra_body_params	向所有模型 HTTP 请求 body 中追加额外的 JSON 参数，与模型自身 body_template 合并。默认 "{}"。
rds.ai_extra_headers	向所有模型 HTTP 请求 header 中追加额外的 HTTP 头（JSON 对象格式，key 为头名，value 为头值）。默认 "{}"。

权限与安全

本章节说明 rds_ai 插件的权限模型和相关的安全配置。

角色与权限

rds_ai 的功能根据操作的敏感性，分为不同权限级别的用户可执行。

操作类型	函数示例	所需权限	说明
管理操作	add_model, remove_model, set_apikey, set_rerank_apikey, set_default_model, set_max_response_size, set_proxy, unset_proxy	超级用户（Superuser）	这些函数会修改插件的配置（元数据表），涉及安全和系统设置，因此仅限超级用户执行，权限可按需委派
调用操作	ai_query, ai_embed, ai_rank, ai_retrieve, ai_rag	所有用户	任何有权连接到数据库的用户都可以调用这些 AI 功能。ai_retrieve、ai_rag 以 SECURITY INVOKER 运行，调用者必须具备来源表及列的 SELECT 权限，RLS 继续生效；ai_rank 以 SECURITY DEFINER 运行。
查看操作	list_model, get_apikey, get_rerank_apikey, get_default_model, get_proxy_info	所有用户	所有用户都可以查看已配置的模型列表、默认模型和代理配置。API Key 相关 getter 仅返回 key_name，不返回任何明文或密文；get_proxy_info 不返回代理密码。
统计操作	rds_ai_stat, rds_ai_stat_detail, rds_ai_stat_reset, get_token_day, get_token_month, throttle_reset_day, throttle_reset_month	超级用户（Superuser）	统计信息的查看和重置权限也仅限于超级用户。

API 密钥安全

加密存储：你通过 rds_ai.set_apikey 设置的 API Key 会使用 pgcrypto 插件进行加密后存储在数据库的系统表中，不会以明文形式暴露。

全局唯一：每个数据库实例内只维护一个全局 API Key，所有模型的调用都使用此密钥。

实例重建后失效：当数据库实例因迁移、恢复等操作重建后，用于加密的内部密钥会发生变化，导致之前存储的 API Key 解密失败。此时，你需要重新执行 rds_ai.set_apikey 来设置新的 API Key。

Rerank 专用 Key：1.3 版本支持为 rerank 服务配置专用 API Key（set_rerank_apikey），优先于全局 Key 使用。

网络访问安全

域名白名单：rds_ai 插件通过 rds.ai_domain_allowlist GUC 参数限制了可访问的外部域名。只有在此白名单中的域名，插件才会发起 HTTP 请求。这可以有效防止插件被用于访问未经授权的恶意网站。

配置权限：只有超级用户可以修改域名白名单。

HTTP 代理：支持通过代理转发模型 HTTP 请求，代理密码加密存储。仅在网络路径要求代理时配置。

资源限制与保护

响应大小限制：rds_ai.set_max_response_size 函数允许你为每个模型设置响应体的大小上限，防止因单个请求返回超大内容而导致数据库内存溢出。

统计模型数量限制：rds.ai_max_model_num 参数限制了内存中统计信息表能容纳的最大模型数量（默认为 64 个），以保护小规格实例的内存资源。

并发请求限制：rds.ai_max_concurrent_requests 控制最大并发 HTTP 请求数，防止过多并发请求影响数据库性能。

Token 限流：通过 rds.throttle_token_day 和 rds.throttle_token_month 控制日/月 Token 消耗上限，避免意外的高额费用。

常见问题 (FAQ)

Q1: 调用 ai_query 或 ai_embed 时报错 ERROR: HTTP request timed out，怎么办？

A: AI 模型调用可能耗时较长，默认的 5 秒超时（rds.ai_timeout_msec）可能不够。你可以根据网络情况和模型响应时间，在当前会话中适当调高此值，例如设置为 30 秒：SET rds.ai_timeout_msec = 30000;。也可同时调整连接超时 rds.ai_connect_timeout_msec。检查端点连通性和代理配置；不要无评估地将超时设为 0。

Q2: 调用 AI 函数时报错，提示域名不在白名单内，如何处理？

A: 出于安全考虑，插件只能访问已加入白名单的域名。请联系你的数据库管理员（或如果你有权限），使用 ALTER SYSTEM SET rds.ai_domain_allowlist = '...'; 命令，将你的模型服务域名添加到白名单中，并执行 SELECT pg_reload_conf(); 使其生效。

Q3: 实例重启后，Token 消耗统计和限流信息为什么被清零了？

A: 当前版本中，模型的调用统计和限流计数信息存储在内存中，并未持久化。因此，当数据库实例重启后，这些信息会被重置为零。日/月 Token 限流计数和 rds_ai_stat_detail() 调用统计都保存在共享内存中，PostgreSQL 重启后会清零。调用统计不写本地文件，也不会在重启后恢复；stats_reset 字段用于标识当前统计窗口的起始时间。

Q4: 我设置了 rds.throttle_token_day 进行每日限流，为什么感觉重置周期不是标准的 24 小时？

A: 限流的每日重置依赖于数据库的 TimeZone GUC 参数。如果你修改了 TimeZone（例如从 UTC+0 改为 UTC+8），在修改当天，重置周期会相应缩短（示例中会变为 16 小时）。从第二天开始，将恢复为标准的 24 小时重置周期。

Q5: CREATE EXTENSION rds_ai 失败怎么办？

A: 可能原因包括：缺少 pgcrypto/vector 依赖、未将 rds_ai 加入 shared_preload_libraries、权限不足或 PostgreSQL 版本不支持。请检查 pg_available_extensions、shared_preload_libraries、当前角色和服务器版本。安装依赖并重启实例，由平台授权后重试。

Q6: 报错 "model does not exist" 或 "default model is not set" 怎么办？

A: 模型未注册、名称错误或默认绑定为空。执行 list_model() 和 get_default_model() 检查。注册对应模型，或调用 set_default_model 设置默认模型；也可在调用时显式传入 model_name。

Q7: 调用 ai_retrieve 或 ai_rag 时报权限错误怎么办？

A: 这两个函数以 SECURITY INVOKER 运行，会按调用者身份检查来源表及相关列的 SELECT 权限，行级安全策略（RLS）也继续生效。请用同一角色直接查询来源列验证权限，并检查 RLS 策略。修正标识符或授予最小必要权限。

Q8: 向量维度或类型报错怎么办？

A: embedding 输出维度或表示与来源向量列不一致。检查目标列的类型和维度（typmod），确保 embed_args 中的 dimensions 与列定义一致，必要时重建错误的向量数据。

Q9: RAG 发出 rank model WARNING 是什么意思？

A: 表示显式传入的 rank_model 和 ai_rank 默认模型都为空。如果业务不需要 rerank，WARNING 可以忽略，RAG 会继续执行（跳过重排序步骤）。如需 rerank，请设置 ai_rank 默认模型或在调用时显式传入 rank_model。

Q10: 从 1.2 升级到 1.3 需要注意什么？

A: 升级前必须先执行 CREATE EXTENSION vector;（1.3 硬依赖 pgvector）。升级会自动注册预置模型并补齐缺失的 ai_query 和 ai_embed 默认模型，但不会在同一个升级事务中设置 ai_rank 默认模型。需要重排序时，升级完成后执行 SELECT rds_ai.set_default_model('ai_rank', 'qwen3-reranker-0.6b');。从 1.0/1.1 升级必须先升级到 1.2，再升级到 1.3，不能跳过中间版本。

最近更新时间：2026.08.27 18:05:54

这个页面对您有帮助吗？

有用

无用