sqlbot智能问数使用简介：用 TaoToken 统一 Key 打通 ChatBI 问数链路

1. 为什么要在 ChatBI 场景里折腾统一 KeySQLBot 这类智能问数系统本质是把「自然语言 → SQL → 数据结果 → 图表」这条链路用大语言模型和 RAG 串起来。业务同事在对话框里敲一句「上个月华东区退货率最高的三个品类」系统要先把这句话拆成意图再去 schema 里检索相关表和字段拼出提示词交给模型生成 SQL最后执行并渲染。整条链路里模型调用是最不稳定也最贵的一环。问题就出在这里SQLBot 本身要配一个 OpenAI 兼容的模型服务你手头可能还有别的 AI 工具——写代码的、做文档的、跑 Agent 的。如果每个工具都单独配一套 Key、单独记一个 base_url时间一长就是一团乱麻。更麻烦的是SQLBot 的模型配置项里要填base_url、api_key、model_name一旦模型侧报错你根本分不清是 SQLBot 的提示词问题还是模型通道的问题。我试过把 SQLBot 的模型出口统一收拢到一个兼容 OpenAI 协议的网关用同一套 Key 管理所有 AI 工具的调用。这样做的直接好处是SQLBot 里配的base_url和api_key跟其他工具保持一致排障时只需要看一个地方的日志换模型也只改一个配置项不用每个工具翻一遍。这篇就围绕 SQLBot v1.5.0把从部署、配 Key 到跑通一次问数的完整路径写清楚配置骨架可以直接复制。2. TaoToken 在问数链路里的位置先把架构讲明白。SQLBot 的容器跑起来之后内部有两个端口8000 是控制台和问数主服务8001 是 MCP Server。问数请求进来后SQLBot 会调用你在「系统配置 → AI 模型配置」里指定的模型服务。这个模型服务只要是 OpenAI 兼容接口就行/v1/chat/completions能通就可以。TaoToken 在这里扮演的就是那个「OpenAI 兼容出口」。你不需要改 SQLBot 的源码也不用装额外插件只要在模型配置里把base_url指向 TaoToken 的 API 地址把api_key填成在控制台生成的 KeySQLBot 就会把提示词发到 TaoToken再由它路由到具体模型。对 SQLBot 来说它只是换了一个模型供应商其他逻辑完全不变。这样做还有个隐性收益SQLBot 的 RAG 检索会把表结构、字段描述、示例 SQL、术语库一股脑塞进提示词输入 token 经常很大。统一通道之后你可以在一个地方看到每次请求的 token 消耗方便判断是不是提示词塞太多了。后面排错章节会专门讲 424 错误码那个基本就是输入超限引起的。需要提前准备的东西一台能跑 Docker 的机器2 核 4G 起步问数场景建议 4 核 8G、SQLBot v1.5.0 镜像、一个 TaoToken 账号和 API Key。Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys 生成后先复制存好页面刷新就看不到了。3. 可复制的配置骨架3.1 启动 SQLBot 容器先按官方方式把服务拉起来。下面这条命令我加了注释注意SERVER_IMAGE_HOST里的 IP 要改成你服务器的实际地址否则图表图片加载不出来。docker run -d \ --name sqlbot \ --restart unless-stopped \ -p 8200:8000 \ -p 8201:8001 \ -e SERVER_IMAGE_HOSThttp://192.168.1.100:8201/images/ \ -v ./data/sqlbot/excel:/opt/sqlbot/data/excel \ -v ./data/sqlbot/images:/opt/sqlbot/images \ -v ./data/sqlbot/logs:/opt/sqlbot/logs \ -v ./data/postgresql:/var/lib/postgresql/data \ swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/dataease/sqlbot:v1.5.0启动后访问http://服务器IP:8200/默认账号admin密码SQLBot123456。第一次登录会强制改密码改完进系统配置。3.2 模型配置settings.json 骨架SQLBot 的模型配置在界面上填但底层存的就是一份 JSON。如果你要做批量部署或者版本管理可以直接参考这个结构。字段名以你实际版本为准下面这份是 v1.5.0 的形态{ ai_model: { name: taotoken-gateway, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model_name: gpt-4o-mini, temperature: 0.1, max_tokens: 4096, timeout: 120 }, sqlbot: { limit_rows: 1000, enable_limit: true } }几个参数值得单独说。temperature设成 0.1 是因为问数要的是稳定 SQL不是创意文案温度高了模型容易自由发挥写出跑不通的语句。max_tokens给 4096 是留足生成复杂 SQL 的空间但别设太大否则模型可能啰嗦地输出一堆解释。limit_rows默认 1000SQLBot 会在生成的 SQL 最外层套一个LIMIT 1000某些聚合场景这个限制会干扰结果按需关掉。3.3 config.toml 骨架如果你是用配置文件方式管理或者在做 MCP 客户端接入可以参考这份 TOML。MCP 的地址指向 8001 端口[sqlbot] base_url http://192.168.1.100:8200 mcp_url http://192.168.1.100:8001/mcp transport sse [ai_gateway] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 default_model gpt-4o-mini temperature 0.1 max_tokens 4096MCP 那段对应的是 SQLBot 的 MCP Server客户端配置里写transport sseURL 填http://your-server-ip:8001/mcp。这样别的 AI 工具就能通过 MCP 协议调用 SQLBot 的问数能力而模型出口仍然走 TaoToken。4. 验证一次问数请求配置填完先别急着建数据源用最小成本验证模型通道通不通。SQLBot 的 API 文档在访问地址后加/docs比如http://192.168.1.100:8200/docs。接口需要 JWT 鉴权JWT 用 Access Key 和 Secret Key 换这两个 Key 在「系统配置 → API Key」页面拿。先换 JWTcurl -X POST http://192.168.1.100:8200/api/v1/auth/token \ -H Content-Type: application/json \ -d { access_key: 你的AccessKey, secret_key: 你的SecretKey }预期返回里有一个token字段复制出来。然后发一次问数请求curl -X POST http://192.168.1.100:8200/api/v1/chat/query \ -H Authorization: Bearer 上一步的token \ -H Content-Type: application/json \ -d { datasource_id: 1, question: 统计每个月的订单总金额, stream: false }如果模型通道正常返回体里会包含生成的 SQL 和查询结果。SQL 大概长这样SELECT DATE_TRUNC(month, order_date) AS month, SUM(amount) AS total_amount FROM orders GROUP BY 1 ORDER BY 1;看到这个就说明链路通了SQLBot 把问题转成了 SQL模型调用走的是 TaoToken结果也回来了。如果返回的是错误码往下看排错章节。5. 本篇常见错排查5.1 错误码 424输入 token 超限这是问数场景最高频的报错。日志里会出现for chunk in sql_res:这样的内容很多人第一反应是 SQLBot 的代码 bug其实大概率是模型侧返回了 424原因是输入 token 超过了模型上限。SQLBot 的 RAG 会把 schema、字段描述、示例 SQL、术语库全塞进提示词表一多输入就爆炸。处理办法分两步。第一步在 TaoToken 侧确认当前模型的上下文窗口换一个窗口更大的模型。第二步在 SQLBot 的模型配置里调maxSeqLen和maxInputTokenLen这两个参数把输入长度压到模型能接受的范围内。同时回头精简数据源无关的表直接剔除字段描述别写小作文。5.2 模型配置保存后不生效改完模型配置记得点保存并重启问数服务有些版本配置是启动时加载的。另外检查base_url结尾不要多写/v1SQLBot 内部会自己拼/v1/chat/completions你写重了会变成/v1/v1/chat/completions直接 404。5.3 图表图片加载不出来这是SERVER_IMAGE_HOST没配对。容器启动时那个环境变量的 IP 必须是外部能访问到的服务器地址不能写127.0.0.1否则浏览器请求图片时指向的是你自己的电脑。改完环境变量要重新创建容器docker restart不生效。5.4 非标准 OpenAI 接口接入如果你用的模型服务不是标准 OpenAI 协议比如某些私有化部署的接口SQLBot 直连会失败。稳妥做法是在中间加一层网关做协议转换把非标准接口包装成/v1/chat/completionsSQLBot 这边只认标准协议。TaoToken 本身就是标准 OpenAI 兼容出口所以 SQLBot 侧不需要做任何适配。5.5 问数结果不准这通常不是模型通道的问题而是业务上下文没配好。提升准确率的思路是系统性地喂上下文数据源只保留相关表给字段加别名和详细描述描述越具体模型越懂字典值做转换格式写成「枚举值key1字典1, key2字典2」手动定义表之间的连接关系提供标准示例 SQL 让模型学习复用建术语库消除指标歧义。这些做完同一个问题的 SQL 质量会有明显提升。6. 把 Key 和通道固定下来跑通一次之后建议把模型配置固化。SQLBot 的模型出口指向 TaoToken 的 API 地址https://taotoken.net/apiKey 用控制台生成的那一个其他 AI 工具也复用同一套。这样做的价值在排障时最明显问数结果不对你先看 TaoToken 侧的请求日志确认模型有没有正常返回如果模型返回正常问题就在 SQLBot 的提示词或数据源配置如果模型侧就报错那跟 SQLBot 无关直接查通道。长期跑编码和 Agent 场景的话可以考虑用 Coding Plan 把额度固定下来地址是 https://taotoken.net/coding-plan 。模型对话调试用 https://taotoken.net/chat 接入文档在 https://taotoken.net/doc 。SQLBot 的 MCP 接入和 API 细节官方文档在 dataease.cn/sqlbot 下有对应章节配合本篇的配置骨架基本能覆盖从部署到问数的全流程。最后留一个实操建议第一次配完先别接生产库拿一张测试表跑「统计每月订单总金额」这种简单问题确认 SQL 生成和结果返回都正常再逐步加表、加术语库、加示例 SQL。问数准确率是喂出来的不是配出来的。