seekdb AI 函数调试与回归

把一个失败现象收敛为可复现 SQL、请求与响应证据、最小修复和对应回归。先定位失败发生在哪一层，再决定是否扩大数据量。运行环境必须由用户提供或从当前工作区核实；不假设安装本 Skill 就拥有 seekdb、编译产物、数据库账号或 Mock 服务。

先判定失败层级

| 现象 | 先找的证据 | 后续动作 | | --- | --- | --- | | 平台只显示“执行失败” | 具体错误、提交 SHA、分支是否含该提交、远端能否取到提交、题目要求的基线 | 分开排查拉取、构建、启动、连接、执行和结果比较；没有日志时保留“原因未确认” | | 编译或链接失败 | 第一处编译错误、CMake 源码目录、编译器版本、实际链接输入 | 确认源码与库来自同一 checkout；不拿旧二进制验证新源码 | | SQL 执行了但没有 HTTP 请求 | SQL 类型检查、NULL 传播、过滤条件、模型与 Endpoint 绑定、执行计划 | 先缩小为一行输入，确认 SQL 是否到达客户端调用层 | | Mock 收到请求但 SQL 失败 | 脱敏后的请求结构、HTTP 状态、响应原文、数据库错误 | 比较 Provider 协议和响应校验；区分请求错误与响应错误 | | 结果数对、内容或顺序错 | 原始行 ID、有效输入槽位、请求局部 index、返回向量 | 检查 NULL/过滤后的压缩映射、响应乱序恢复和跨批偏移 | | 大输入或第二批才失败 | 字节长度、批次边界、列元数据、分配生命周期、失败后的再次调用 | 保留最小失败边界，分别检查 SQL、协议和客户端解码 |

“测试规模不足”是一种待验证的假设。缺少错误日志时，不直接把执行失败归因于隐藏用例或其他赛题。

核对源码与测试入口

在用户指定的仓库根目录读取项目指引，记录下面的只读信息；工作区有未提交修改时，SHA 不能单独代表所测源码。

git status --short
git branch --show-current
git rev-parse HEAD
git log -1 --format='%H %s'
rg --files src unittest tools | rg 'ai_prompt|ai_embed|ai_complete|ai_rerank|openai|ai_func|mock|ai_function'

从当前版本的测试和实现确认函数参数、Endpoint DDL、错误码及默认维度，不从模型名称推断这些信息。只有题目明确指定基线时才比较该基线，不固定要求所有 seekdb 项目使用某个比赛分支。

优先复用仓库现有测试工具，先读其参数说明。下面的文件是部分比赛工作区的可选入口；文件不存在时，查找当前仓库的 CMake/Bazel/mysqltest 配置并使用其实际入口，不下载未知同名文件代替。

test -f unittest/run_competition_tests.py && python3 unittest/run_competition_tests.py --help
test -f tools/deploy/mysql_test/test_suite/ai_function/mock/run_stress.py && python3 tools/deploy/mysql_test/test_suite/ai_function/mock/run_stress.py --help

若使用 CMake，检查 CMakeCache.txt 中的 CMAKE_HOME_DIRECTORY、compile_commands.json 与目标二进制路径是否属于当前 checkout。记录编译日志及测试二进制；源码提交时间不能证明二进制包含该提交。

六类回归检查

按本次改动选取相关行，先运行最小用例，再扩展到异常和边界。

| 功能 | 输入与边界 | 可观察断言 | | --- | --- | --- | | AI_PROMPT | TEXT/LONGTEXT、JSON 数组/对象、嵌套 Prompt、重复占位符、非法下标、中文和转义 | 结果逐字符比较；重复占位符全部正确替换；非法输入按接口约定报错；关注字节与字符差异 | | AI_EMBED 单行 | 默认/显式维度、NULL、0/负数/非整数维度、坏 JSON、空向量、布尔/字符串/非有限元素 | 验证向量类型、维度和每个元素；显式维度必须匹配；默认维度行为以接口契约为准 | | AI_COMPLETE | 字符串、AI_PROMPT、NULL/JSON config、长文本、temperature/max_tokens | 请求中的字段与值正确；正文非空性按接口约定检查；错误结构不被当作成功文本 | | Provider | OpenAI 与原生 Ollama、Provider 大小写、Endpoint 修改、Ollama 无密钥 | 选择正确路径和字段；Ollama 生成关闭流式；不强制给免密协议添加密钥 | | AI_RERANK | 字符串/对象文档、文本字段、相同分数、分批、越界/重复 index | 响应 index 属于当前请求；映射回原始 ID/对象；全局排序稳定；数量符合参数契约 | | AI_EMBED 跨行 | NULL 穿插、过滤、ORDER BY、LIMIT/OFFSET、多批、响应乱序、后续批失败 | 逐行 ID 与向量对应；HTTP 请求确实包含多条输入；不得用 SQL 返回行数证明实现了请求批量 |

构造有区分度的确定性 Mock

Mock 只代替 HTTP 模型服务，SQL 必须走真实 seekdb 引擎。测试夹具可以使用固定响应规则，生产实现不能针对测试模型名或特殊输入绕过正常逻辑。

生成带唯一 ID 和不同文本的输入，采用基于完整文本的确定性向量规则；预期值从原始夹具独立计算，不复用待测解析或映射函数。不要让所有文本返回同一向量，否则行错位可能被掩盖。

协议分别处理：

OpenAI Completion：检查 messages，读取 choices[0].message.content。
OpenAI Embedding：检查 input，将 data 顺序打乱但保留合法的请求局部 index，验证引擎恢复输入顺序。
Ollama Generate：检查原生 /api/generate 的 prompt、stream:false 和 options，返回协议对应的 response/完成状态。
Ollama Embed：检查 /api/embed 和 embeddings，不要套用 OpenAI 的 data/index 响应格式。
Rerank：按所选 Provider 的结构返回，制造跨批不同分数与同分文档，验证全局排序及稳定性。

依次注入畸形 JSON、缺字段、空值、重复/越界 index、维度错误、HTTP 错误、截断响应和后续批失败。错误请求后再发一个正常请求，检查缓冲区、结果槽位和连接是否恢复；将允许的重试次数与真实 HTTP 请求数对照。

请求日志记录用例 ID、路径、请求编号、输入数量和脱敏响应，不记录 Authorization、访问令牌或真实业务文本。测试数据必须是合成数据。

批量映射与规模选择

分开维护以下三层索引，不能把某一层的 index 当作另一层使用：

SQL 原始行及输出槽位，包括 NULL、skip 标记和已过滤的行。
本次 HTTP 请求中压缩后的有效输入槽位。
Provider 返回的局部 index，或协议规定的数组位置。

对每条有效响应检查 index 范围、重复和缺失，再通过显式映射写回 SQL 槽位。对 NULL 行验证 NULL 传播；是否发送空请求及如何处理异常必须符合现有接口契约。

从实现或请求日志得到实际批量上限 B，覆盖 0、1、B−1、B、B+1、2B+1 个有效输入，并在边界两侧插入 NULL。若 B 可配置，同时覆盖两个配置值；不要假定某个版本的固定批大小适用于所有版本。

随后在独立测试库增加行数和并发。每阶段记录输入数、有效输入数、SQL 输出数、HTTP 请求数、每请求输入数及失败位置。只在有性能目标时报告吞吐和延迟，并记录机器、缓存、并发与样本次数；单次耗时不能证明性能提升。

特别检查长中文表达式的结果列名。如果客户端在读取列元数据时解码失败，先检查 UTF-8 字符边界截断；不要仅给表达式加短别名来掩盖数据库返回的非法列名。

执行与修复约束

使用独立测试实例、数据库和唯一对象前缀，先确认端口和数据目录。启动服务、执行 DDL/DML 和故障注入要在用户授权的测试范围内；不要改动现有业务实例或停掉非本次启动的服务。测试清理只处理本次拥有的对象。

容器中的 127.0.0.1 指向容器自身。分别确认测试客户端到数据库、数据库到 Mock 的连通性；客户端能访问 Mock 不证明 seekdb 能访问它。0.0.0.0 是监听地址，Endpoint 应使用数据库进程可到达的具体地址。

先保存失败 SQL、输入、请求响应与日志，再修改引擎。保留已有测试断言，新增能在修复前失败、修复后通过的回归；不修改官方预期输出来迁就错误结果。遵循当前项目的 C++ 规范和构建流程。

修复后先跑相关单测和最小复现，再跑涉及的 SQL 主流程与边界。只有出现新修改、新失败或未解决的疑点才重复已通过的检查。一次失败不能自动触发无限重试或扩大压力；按测试预算停止并留下可复现证据。

交付结果

给出修复结论、代码位置、所测 branch/完整 commit、未提交改动、构建环境、具名用例结果和证据路径。若用户要求提交或推送，按用户指定分支执行，并确认远端 SHA；不要自动发起比赛提测。

将“静态审阅”“编译通过”“Mock 协议测试通过”“真实 SQL 回归通过”和“平台计分通过”分别报告。未运行的项目写明未运行；自建 Mock 不能称作官方 Mock，本机测试不能称作 Linux 评测通过。纯本地失败日志不要写进公开 Skill 页面。

可用请求示例：

“AI_EMBED 过滤后有一行向量对应错了，请定位并补一个复现用例。”
“检查 Ollama 无 API Key 的生成和 Embedding 协议，使用本地 Mock。”
“这个提交只有平台执行失败提示，先确认基线和构建证据，再决定测试范围。”

参考项目：oceanbase/seekdb。命令和参数以当前 checkout 为准。本 Skill 为独立开发的调试工作流，不代表 OceanBase 官方评测工具。