模型管理

查看、添加、删除模型。

检查默认模型是否完整覆盖 chat、embedding、rank 等函数族。

切换模型前评估兼容性、吞吐和成本差异。

示例：盘点模型并验证默认路由

适用场景：升级、切换模型或排查“未配置默认模型”错误前，先确认模型目录与默认路由。以下查询为只读；路由切换示例放在事务中并回滚，不会留下配置变更。设置默认模型需要环境特权角色或已被授予对应权限的角色。

示例：盘点模型与默认路由

典型输出：

结果解读：list_model() 中应存在计划使用的模型，且类型与函数族匹配：chat/llm 对应 ai_query，embedding 对应 ai_embed，rank 对应 ai_rank。get_default_model() 的 model_name 为空表示该函数族没有默认模型，单参数调用会失败。

异常排查：目标模型不存在时先注册模型或运行预置模型加载；类型不兼容时不要强行切换，应选择正确类型的模型；模型名称和 ID 冲突时先核对现有记录，不要直接删除正在使用的模型。

Token 用量与配额

统一关注 Token 持久化统计与集群配额。

建立按模型、按函数族、按业务场景的用量视图。

高频任务建议在业务侧加缓存、限速或批处理机制。

Token 用量持久化与跨节点配额同步能力建议纳入常规巡检项，而不是只在超额时报错后再处理。

示例：设置配额并检查同步健康度

适用场景：变更实例配额后确认 Agent 已接受配置，并判断当前读数来自集群快照还是本地降级统计。set_token_quota 会修改实例级配额，需在变更窗口由环境特权角色执行；示例数值应替换为实际策略。

示例：Token 配额与同步检查

典型输出：

结果解读：usage_scope = 'cluster' 且 cluster_usage_stale = false 表示使用新鲜的集群快照；healthy、quota_available = true、cluster_usage_available = true 表示同步链路正常。配额为 0 表示不限额，此时剩余额度和百分比为 NULL。

异常排查：disabled 表示导出未启用；initializing 表示尚未完成首次同步；degraded 时先看稳定错误码和下一次重试时间，再检查 Agent 可达性。非零月配额必须大于等于日配额，负数会被拒绝。

元数据与预置模型同步

load_preset_models()：负责按需落仓平台预置模型。

load_ai_meta：负责 AI Meta 全量同步。

在版本升级、模型列表异常或环境恢复后，优先检查这两类能力是否执行正常。

示例：恢复预置模型并安全触发元数据同步

适用场景：新安装 1.4 版本插件、版本升级后预置模型缺失，或平台已经下发新的 rds.ai_meta_json。两个加载函数都需要高权限；执行前不要把包含密文的配置值复制到工单或日志。

示例：预置模型与平台元数据同步

典型输出：

结果解读：load_preset_models() 可重复执行，不覆盖已有的非空默认路由。meta_configured = false 表示当前没有平台元数据，调用 load_ai_meta() 将安全地不做任何变更；为 true 时，加载器会整体校验并应用 API Key、代理、模型和默认路由。

异常排查：JSON 格式、模型字段、重复名称或 ID、密文解密任一失败都会使整次加载回滚。失败后先修复配置源，再重试；不要直接修改 rds_ai_sys 内部表。

稳定性治理建议

明确超时策略、重试策略和降级路径。

把域名 allowlist、API Key、默认模型完整性纳入配置巡检。

把 auto embed 的 pending / failed 作为单独指标观察。

示例：一次完成运行参数与凭据元数据巡检

适用场景：AI 请求超时、并发拥塞、配额同步异常或代理链路故障时，先采集一份不包含密钥和代理密码的配置快照。

示例：只读稳定性巡检

典型输出：

结果解读：context = 'user' 的参数可在会话中调整；sighup 需要修改配置后 reload；postmaster 需要重启 PostgreSQL。get_apikey() 只返回 Key 名称，不返回密钥；代理查询同样不会返回密码。

异常排查：连接阶段失败优先看 connect timeout、域名 allowlist 和代理；请求已建立但响应慢时看 timeout 与并发上限；Auto Embed 长期无任务执行时确认 worker 数量不为 0，并结合后文任务状态查询。

成本治理建议

优先用任务型函数替代不必要的通用生成调用。

对高频问答引入缓存、摘要压缩和检索裁剪。

对长文本处理建立长度门槛和分段策略。

示例：定位本月 Token 消耗最高的函数

适用场景：配额增长过快时，先按公开函数族计算 Token 占比，再回到业务侧定位高频 SQL、长输入或重复调用。查询为只读；无用量时占比返回 NULL，不会发生除零错误。

示例：按函数统计本月 Token 占比

典型输出：

结果解读：Token 占比高且请求数低，通常意味着单次输入或输出过长；请求数和 Token 同时高，通常意味着高频调用。应结合业务日志定位调用方，不能只凭函数汇总判断具体 SQL。

优化建议：ai_query 优先压缩上下文并限制输出长度；ai_embed 优先去重、批处理并避免重复向量化；ai_rag 优先收紧召回数量、切片长度和重排范围。调整后连续观察日用量与月度趋势。

典型排查顺序

先看配置：默认模型、API Key、域名 allowlist。

再看资源：配额、Token 用量、模型端可达性。

最后看数据与调用链：切片、召回、RAG prompt、auto embed 状态。

示例：排查 Auto Embed 堆积或失败

适用场景：源表已有文本但向量列迟迟为空，或监控发现 Auto Embed 任务积压。以下查询只读取公开聚合状态，不暴露源文本、主键、请求体、响应体或凭据。

示例：Auto Embed 任务状态

典型输出：

结果解读：pending_jobs 短时增长且 running_jobs 大于 0 通常表示正在消费；持续增长且运行数为 0 时，检查 worker 配置和模型可用性；failed_jobs 大于 0 时，从 latest_error 判断是网络、鉴权、模型响应还是向量维度问题。查询返回 0 行表示尚未注册任何映射。

恢复操作：修复根因后，可对已启用映射执行 SELECT rds_ai.enqueue_auto_embed('docs_embed'); 重新扫描缺失向量的行。若要覆盖已有向量，必须显式传入 true；该操作可能产生大量外部请求，应先评估数据量与成本。禁用映射会停止产生新任务，但不会替代根因排查。

完整排查示例：ai_query 报默认模型未配置

如果第一条返回空模型，先加载预置模型或设置兼容的默认模型；如果第二条返回 0 行，配置 API Key；如果前两项正常，再检查域名 allowlist、代理和超时配置。Token 同步状态用于判断配额链路是否健康，它不是模型请求成功的充分条件。

AI 原生 BaaS 平台 Supabase 版