本文汇总了 rds_ai 提供的对外接口。语义函数的完整定义、参数、返回、错误行为和可执行示例放在对应能力页；管理、配置、统计、限流接口的详细信息可在本文获得。

权限约定

权限类别	说明
普通用户接口	语义函数、Token 用量只读接口，以及 get_apikey、get_rerank_apikey、get_default_model、list_model 默认授予 PUBLIC 执行权限。
可委派管理接口	模型、凭据、默认模型、Token 配额和 Auto Embed 管理接口默认授予环境高权限角色，并带 GRANT OPTION；Neon 环境为 neon_superuser，其他环境为 pg_rds_superuser。
超级用户接口	代理配置与元数据加载接口默认不授予 PUBLIC 或上述环境高权限角色，只允许超级用户调用。

所有运行时接口在扩展升级期间都会拒绝执行；调用方还必须具备目标函数的 EXECUTE 权限。

语义函数

以下函数的 API 细节直接查看对应子文档：

函数	能力	API 文档	版本
ai_query	语义生成	语义生成（ai_query）	1.0
ai_embed	向量生成	语义向量化（ai_embed）	1.0
ai_retrieve	语义检索	语义检索（ai_retrieve）	1.3
ai_rank	文本重排	文本重排（ai_rank）	1.3
ai_rag	检索增强生成	检索增强生成（ai_rag）	1.3
ai_summarize	语义摘要	语义摘要（ai_summarize）	1.4
ai_classify	语义分类	语义分类（ai_classify）	1.4
ai_extract	语义抽取	语义抽取（ai_extract）	1.4

模型管理接口

定义

模型管理接口负责注册、查询和删除模型元数据，以及限制单个模型允许接收的 HTTP 响应大小。

语法

参数

接口	参数说明
add_model	model_id 为服务端模型 ID；model_name 为数据库内唯一名称；base_url 为端点；model_type 支持 chat、llm、embedding、rank；text_template 接收 model ID 与输入文本两个 format() 参数；json_path 和 token_path 是以响应文本为参数的 SQL 模板。
list_model	无参数。
remove_model	model_name：要删除的数据库内模型名称。
set_max_response_size	model_name_v：模型名称；max_response_size_v：响应头加响应体允许的最大字节数，0 表示不限制。
load_preset_models	无参数。

返回

add_model、remove_model、set_max_response_size 和 load_preset_models 成功时返回 void。list_model 返回全部模型配置，包括请求模板和响应提取模板，但不包含 API Key。load_preset_models 可重复调用，只补充缺失的预置模型和默认绑定，不覆盖已有的非 NULL 默认绑定。

错误行为

add_model 的必填参数为 SQL NULL、名称或 ID 冲突、模型类型非法时抛出错误；写入具有事务原子性。

remove_model 或 set_max_response_size 找不到模型时抛出错误；响应大小小于 0 时抛出错误。

load_preset_models 在扩展升级期间拒绝执行；权限不足时由 PostgreSQL 抛出权限错误。

示例

API Key 接口

定义

全局 API Key 用于一般模型请求；专用 rerank API Key 优先用于 ai_rank 和 RAG 重排，未配置时回退到全局 API Key。

语法

参数

接口	参数说明
set_apikey	key_name 为凭据名称，api_key 为待加密保存的全局密钥；新值覆盖已有单条凭据。
get_apikey	无参数。
set_rerank_apikey	key_name 为凭据名称，api_key 为待加密保存的 rerank 密钥；新值覆盖已有单条凭据。
get_rerank_apikey	无参数。

返回

两个 setter 成功时返回 void；两个 getter 返回零行或一行 key_name，只暴露非敏感名称，不返回明文或密文 Key。无配置时 getter 返回零行。

错误行为

setter 参数为 SQL NULL、API Key 长度达到或超过 4096 字节、加密环境标识缺失、扩展升级中或权限不足时抛出错误。getter 不会因凭据未配置而报错。

当前 1.4 版本没有 remove_apikey 接口；重新调用 setter 会覆盖原凭据。

示例

代理接口

定义

代理接口维护一条实例级 HTTP 代理配置，密码加密存储且不会通过查询接口返回。

语法

参数

接口	参数说明
set_proxy	proxy_url 必须以 http:// 开头；proxy_user 和 proxy_pwd 可省略，但提供密码时必须同时提供用户名。
unset_proxy	无参数。
get_proxy_info	无参数。

返回

set_proxy 和 unset_proxy 成功时返回 void，后者重复执行仍成功。get_proxy_info 返回零行或一行 proxy_url、proxy_user，不返回代理密码；无配置时返回零行。

错误行为

URL 为空、协议非法、URL 达到 2048 字节、用户名达到 512 字节、密码达到 4096 字节、只有密码没有用户名、扩展升级中或权限不足时抛出错误。

示例

默认模型接口

定义

默认模型接口为 ai_query、ai_embed 和 ai_rank 维护默认路由。

语法

参数

p_function_name 只能是 ai_query、ai_embed 或 ai_rank。

p_model_name 为已注册且类型兼容的模型名称；传 SQL NULL 可清除该函数的默认绑定。

返回

set_default_model 成功时返回 void。get_default_model 始终按上述三个函数的顺序返回三行；未绑定时 model_name 为 SQL NULL。

错误行为

函数名为 SQL NULL、模型不存在、模型类型不兼容、权限不足或处于扩展升级期间时抛出错误。

示例

元数据加载接口

定义

元数据加载接口将实例 GUC 中的模型配置导入扩展目录，默认仅超级用户可执行。

语法

参数

接口	输入
load_ai_meta	无函数参数；读取 rds.ai_meta_json，支持 api_key、rerank_api_key、proxy、models、default_models。
load_default_models	set_default 默认为 true；读取兼容参数 rds.default_model_meta_json，为 true 时同时设置 query/embed 默认模型。

返回

两个接口成功时返回 void，配置为空时直接成功返回。load_ai_meta 原子应用本次全部变更；兼容格式的 load_default_models 不支持 ai_rank 默认模型。

错误行为

JSON 结构、字段类型或模型类型非法，密文无法解密，模型名称或 ID 冲突，默认模型类型不兼容，set_default 为 SQL NULL，权限不足或处于扩展升级期间时抛出错误。单次调用中的所有变更随事务一起回滚。

示例

Token 用量与配额接口

定义

Token 用量接口按 Asia/Shanghai 计费周期提供集群或本地用量、按函数明细和同步健康状态，并通过管理接口原子更新日/月配额。

语法

参数

接口	参数	说明
set_token_quota	day_quota、month_quota	两个配额都必须大于或等于 0；非零月配额必须大于或等于日配额。经确认的 0, 0 表示日/月均不限量。
5 个只读接口	无	读取当前共享状态，不修改计量、配额或同步检查点。

返回

接口	返回与行为
set_token_quota	成功同步 Agent 并安装 Agent 返回的新配置版本后返回 void。
token_usage_day / token_usage_month	各返回当前 Asia/Shanghai 日/月半开计费区间的一行汇总。usage_scope='cluster' 表示新鲜的 Agent 集群快照加尚未确认的本地增量，否则为 local。配额未知或不限量时，remaining_tokens 与 usage_percent 为 SQL NULL。
token_usage_day_by_function / token_usage_month_by_function	按稳定顺序返回 6 个 AI 接口各一行，零用量接口也会出现；每行包含计费区间、函数名、Token 数和请求数。
token_usage_sync_status	返回一行脱敏状态。sync_state 为 disabled、initializing、healthy 或 degraded；不暴露 Agent URL、响应正文、代次或检查点。

错误行为

set_token_quota 遇到负数、非零月配额小于日配额、扩展升级中或权限不足时抛出错误；Agent 不可用、拒绝请求或返回无效内容时，以 token quota synchronization failed: <稳定错误码> 抛错，且不会安装未确认的本地配额。只读接口在扩展未预加载或共享状态不可用时抛出前置状态错误。

示例

GUC 配置参数

参数	上下文	默认值	说明
rds.ai_domain_allowlist	SUSET	空	模型 URL 前缀白名单；为空或不匹配时拒绝调用。
rds.ai_timeout_msec	USERSET	5000	HTTP 总超时，单位毫秒。
rds.ai_connect_timeout_msec	USERSET	1000	HTTP 连接超时，单位毫秒。
rds.ai_max_concurrent_requests	SIGHUP	0	实例共享的模型 HTTP 请求并发上限；0 表示不限制。
rds.ai_extra_body_params	USERSET	{}	合并到 query/embed 请求体的 JSON 对象；函数参数中的同名键优先。
rds.ai_extra_headers	USERSET	{}	附加 HTTP 请求头；函数参数优先于 GUC，GUC 优先于模型模板。
rds.ai_rag_query_rewrite	USERSET	off	为 ai_rag 启用检索前问题改写；开启后额外调用一次 LLM。
rds.ai_rag_dynamic_truncate_topn	USERSET	on	根据重排分数断崖动态裁剪低相关上下文，同时至少保留前 5 条。
rds.ai_rag_ushape_char_threshold	USERSET	32768	重排后上下文总字符数达到该值时启用 U-shape 排列；范围为 0–2147483647。
rds.ai_rag_rank_score_threshold	USERSET	0.5	接受重排顺序的最高分下限，范围为 0–1；低于该值时退回原向量检索顺序。
rds.ai_token_usage_export_enabled	SIGHUP	off	是否异步向本地 Agent 导出 Token 用量并接收集群快照和配额。
rds.ai_token_usage_agent_address	POSTMASTER	平台相关	本地 Agent 基础 URL；Neon 默认 http://169.254.254.253:29001，RDS PG 默认 http://127.0.0.1:8888。不要附加 /token_usage/v1/heartbeat；修改后需重启。
rds.ai_token_usage_export_interval_sec	SIGHUP	200	Token 用量导出尝试间隔，范围 200–600 秒；连续错过 3 个间隔后集群快照视为过期。
rds.ai_token_throttle_degraded_policy	SUSET	fail_open	集群用量不可用于执行配额时的策略：fail_open 或 fail_closed。
rds.ai_meta_json	SUSET	空	通用 AI 元数据 JSON，由 load_ai_meta() 导入。
rds.default_model_meta_json	SUSET	空	旧版默认模型数组格式，由 load_default_models() 导入。

Ark 归因相关的 rds.ai_ark_client_request_id 和 rds.ai_ark_domain_name 是编译期固定的只读参数，只支持 SHOW，不能通过 SET 或配置文件修改。更多部署和权限说明见配置与访问控制。

AI 原生 BaaS 平台 Supabase 版