企业官网建设流程全解析

1. 为什么要在 ChatBI 场景里折腾统一 Key

SQLBot 这类智能问数系统，本质是把「自然语言 → 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填成在控制台生成的 Key，SQLBot 就会把提示词发到 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_HOST=http://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，密码SQLBot@123456。第一次登录会强制改密码，改完进系统配置。

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默认 1000，SQLBot 会在生成的 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 = 4096

MCP 那段对应的是 SQLBot 的 MCP Server，客户端配置里写transport = "sse"，URL 填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」页面拿。

先换 JWT：

curl -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结尾不要多写/v1，SQLBot 内部会自己拼/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/completions，SQLBot 这边只认标准协议。TaoToken 本身就是标准 OpenAI 兼容出口，所以 SQLBot 侧不需要做任何适配。

5.5 问数结果不准

这通常不是模型通道的问题，而是业务上下文没配好。提升准确率的思路是系统性地喂上下文：数据源只保留相关表；给字段加别名和详细描述，描述越具体模型越懂；字典值做转换，格式写成「枚举值：key1=字典1, key2=字典2」；手动定义表之间的连接关系；提供标准示例 SQL 让模型学习复用；建术语库消除指标歧义。这些做完，同一个问题的 SQL 质量会有明显提升。

6. 把 Key 和通道固定下来

跑通一次之后，建议把模型配置固化。SQLBot 的模型出口指向 TaoToken 的 API 地址https://taotoken.net/api，Key 用控制台生成的那一个，其他 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。问数准确率是喂出来的，不是配出来的。