SeekDB AI 函数 SQL 助手

在 SQL 引擎内部直接调用大模型：补全、向量化、重排，都通过普通 SQL 表达式完成，不需要在应用层拼 HTTP 请求。

何时使用

写 SELECT ... AI_COMPLETE(...)、AI_EMBED(...)、AI_RERANK(...)、AI_PROMPT(...)
建表后需要对整列文本批量向量化（一次请求带多行）
配置 / 修改 / 删除 AI Model 与 Model Endpoint
排查 AI 函数报错（5083、1210、11112、11114、11116、11118、1227）

不适用：模型效果调优、微调、非 seekdb 的向量数据库。

四个函数

| 函数 | 作用 | 返回 | | --- | --- | --- | | AI_PROMPT(template, arg...) | 把参数按 {0}、{1} 位置代入模板 | 字符串（JSON 参数保留结构） | | AI_COMPLETE(model, prompt [, config]) | 文本补全，config 为 JSON 字符串 | 字符串 | | AI_EMBED(model, text [, dimension]) | 文本向量化，dimension 为正整数 | JSON 数组（json_length() 可测维度） | | AI_RERANK(model, query, docs [, doc_key]) | 对候选文档重排 | JSON 数组（保序、带原始 id/index） |

标准工作流

先建模型，再建端点。CREATE_AI_MODEL 声明类型和模型名，CREATE_AI_MODEL_ENDPOINT 绑定 URL、access_key、provider。
单行验证：SELECT json_length(AI_EMBED('m', 'hello')); 或 SELECT length(AI_COMPLETE('m', 'hi')) > 0;
再跑批量：直接在表扫描里用表达式，引擎会把多行合并成一次请求。
最后校验形状：维度、条数、id 映射是否符合预期。
需要时用 DBMS_AI_SERVICE.DROP_* 清理，避免同名冲突。

-- 1) 模型
call DBMS_AI_SERVICE.CREATE_AI_MODEL(
  'my_embed', '{"type":"dense_embedding","model_name":"text-embedding-v1"}');

-- 2) 端点（openai 兼容协议必须提供 access_key）
call DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT(
  'my_embed_ep', '{"ai_model_name":"my_embed","scope":"all",
                  "url":"https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings",
                  "access_key":"sk-***","provider":"openai","max_concurrency":3}');

-- 3) 单行验证
select json_length(ai_embed('my_embed', 'hello')) as dim;

-- 4) 批量：一个请求多行，NULL 行自动跳过且不打乱顺序
select id, json_length(ai_embed('my_embed', content)) as dim
  from docs order by id;

端点管理要点

模型类型只有四类：completion、dense_embedding、sparse_embedding、rerank。
端点 JSON 常用字段：ai_model_name、url、access_key、provider、request_model_name、max_concurrency（1~1024 的整数）。
provider 取值大小写不敏感（openai、aliyun-openai、siliconflow、ollama 均可，也接受 Ollama、OLLAMA）。
Ollama 端点允许 access_key 为空；openai 兼容协议不允许，空 key 直接报 11114。
修改用 ALTER_AI_MODEL_ENDPOINT(name, json)，只能改 url、access_key、provider、max_concurrency 等，不能改 ai_model_name（报 11116）。
查询现状：select * from oceanbase.DBA_OB_AI_MODEL_ENDPOINTS;、oceanbase.DBA_OB_AI_MODELS。
非 root 用户需要 GRANT CREATE/ALTER/DROP AI MODEL ON *.* TO ...，否则报 1227。

容易写错的地方

AI_PROMPT 的参数必须是字符串类（VARCHAR/CHAR/BINARY/TEXT/BLOB/LONGTEXT/JSON）。传数字、日期、NULL 都会 5083；模板为空串报 1210；参数个数为 0 报 1582。
JSON 参数会被保留结构：AI_PROMPT('{0}', json_object('k', 1)) 得到的是 JSON 而不是 [object] 文本。需要纯文本时显式 CAST(... AS CHAR)。
重复占位符合法：'{0}/{0}/{1}' 会把第 0 个参数代入两次。
AI_COMPLETE 的第三个参数是 JSON 配置字符串，如 '{"temperature":0.2,"max_tokens":16}'；传 NULL 表示用默认值。
AI_EMBED 默认维度由模型决定，显式传维度时必须是正整数字面量或正整数表达式。
AI_RERANK 的文档数组有两种形状：字符串数组，或对象数组。对象数组必须给第四个参数 doc_key 指明文本字段名，否则报 1235；字符串数组传 NULL 即可。
批量时不要手写 UNION 或循环，一次表扫描就够了；引擎负责合并、乱序恢复与 NULL 传播。
弱读（/*+read_consistency(weak) */）下 AI 结果不稳定，不要据此做断言。

交付前检查

python check_ai_sql.py path/to/query.sql

再人工确认三件事：

模型 → 端点 → 函数调用三层名字对得上；
每个 AI_RERANK 的对象数组都带了 doc_key；
批量查询里有 ORDER BY 或主键，便于核对结果与原始行的映射。

参考

sql-reference.md：完整函数签名、端点字段、DDL 清单
error-codes.md：错误码 → 成因 → 修法
rag_pipeline.sql：从建端点到检索重排的完整示例