企业官网建设流程全解析

1. 为什么 MaxKB 里问数总卡在“最后一公里”

如果你正在用 MaxKB 搭知识库问答，大概率遇到过这种尴尬：文档问答很顺，但用户一句“上个月华东区销售额是多少”，系统就开始装傻。原因不复杂——MaxKB 擅长的是检索增强生成，它能把知识库里的文本片段找出来喂给模型，但数据库里的结构化数据不在它的检索范围内。你问它“卖了多少”，它只能从文档里找有没有人写过“卖了多少”，而不是真的去查库。

SQLBot 解决的正是这一段。它把自然语言转成 SQL、执行查询、再把结果整理成表格或图表返回。但 SQLBot 本身是一个独立服务，MaxKB 不会自动认识它。两者之间需要一个协议层来传话，这个协议层就是 MCP（Model Context Protocol）。MCP 让 MaxKB 的工作流能够以“工具调用”的方式去请求 SQLBot，把“用户提问→生成 SQL→查库→返回结果”串成一条链路。

我试过把这条链路跑通，中间踩的坑主要集中在两个地方：一是 MCP 服务的连接配置，二是模型调用时的鉴权。前者是 URL 和 transport 写错就连不上，后者是 Key 和 Base URL 不统一导致 401。这篇就按“MaxKB 工作流 + SQLBot MCP + TaoToken 统一 Key”的组合，把配置和验证过程完整走一遍。适合已经会用 MaxKB 基础功能、想进一步接入外部数据源的人，也适合在搭 Agent 工作流时被鉴权问题卡住的开发者。

核心检索词先明确：SQLBot 是一个自然语言转 SQL 的查询工具，MaxKB 是知识库问答平台，MCP 是两者之间的工具调用协议，TaoToken 提供统一的 API Key 和 Base URL 来打通模型调用。整条链路的目标是：用户在 MaxKB 里提问，工作流通过 MCP 调用 SQLBot，SQLBot 返回查询结果，MaxKB 展示给用户。

2. TaoToken 统一 Key 的前置准备与 MCP 接入配置

在动手配 MaxKB 工作流之前，先把 TaoToken 的 Key 和 Base URL 准备好。这一步不做，后面所有模型调用都会报 401。TaoToken 的作用是给整条链路提供一个统一的模型接入点，你不需要在 MaxKB、SQLBot、MCP 服务里分别配不同的模型供应商，只需要一个 Key 和一个 Base URL。

先到 TaoToken 控制台创建 API Key。地址是 https://taotoken.net/console ，登录后在 API Keys 页面新建一个 Key，复制出来保存好。这个 Key 后面会用在两个地方：一是 MaxKB 的 AI 对话组件里配置模型，二是 MCP 服务如果需要模型能力时调用。Base URL 统一用 https://taotoken.net/api ，注意不要加多余的路径后缀，MCP 配置里如果写错成 /v1 或其他路径，连接会直接失败。

如果你用的是 Claude Code 或类似的编码工具，TaoToken 也支持通过 auth.json 或 settings 配置接入。以 Claude Code 为例，配置文件通常放在用户目录下的 .claude/settings.json 或项目级的 .mcp.json 中。一个可复制的配置片段如下：

{ "mcpServers": { "sqlbot_mcp": { "url": "http://你的服务器IP/mcp", "transport": "sse" } }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoTokenKey" } }

这段配置里，mcpServers 部分定义的是 SQLBot 的 MCP 服务地址，env 部分定义的是模型调用的 Base URL 和 Key。注意 url 里的 IP 要换成你实际部署 SQLBot 的服务器地址，transport 用 sse，这是 MaxKB 和 SQLBot 之间常用的传输方式。如果你用的是 Cline 或 CC Switch 这类工具，配置逻辑类似，核心是三件套：Base URL、Key、Model ID。Model ID 根据你实际使用的模型填写，比如 claude-3-5-sonnet 或 gpt-4o，具体以 TaoToken 文档里的模型列表为准。

MCP 服务配置在 MaxKB 里是写在工具调用组件里的，格式是一个 JSON 对象。原文示例里给的是：

{ "sqlbot_mcp": { "url": "http://<YOUR IP>/mcp", "transport": "sse" } }

这里要注意， 要替换成你的 SQLBot 服务实际地址，如果是本地部署就是 127.0.0.1 或局域网 IP，如果是云服务器就是公网 IP。transport 必须是 sse，写成 stdio 或其他会连不上。另外，如果你的 SQLBot 服务有路径前缀，比如 /api/mcp，那 url 要写全，不能只写域名。

TaoToken 的 Coding Plan 适合长期跑编码和 Agent 任务的场景，如果你打算把这条问数链路做成日常使用的工具，可以考虑用 Coding Plan 来降低频繁调用的成本。接入文档在 https://taotoken.net/doc ，里面有各语言的调用示例和模型列表，配置前建议先扫一眼，确认 Base URL 和 Model ID 的写法。

3. MaxKB 工作流可复制配置：工具调用与 AI 自动调用

MaxKB 里对接 SQLBot 有两种方案：工具调用和 AI 自动调用。工具调用是人工把每个组件串好，稳定性高，适合固定流程；AI 自动调用是给 AI 一段提示词，让它自己决定什么时候调哪个工具，灵活但输出不太稳定。两种方案我都配过，下面把可复制的配置片段和关键参数写清楚。

先看工具调用的配置。整个工作流从“开始”组件出发，依次经过判断器、MCP 调用工具、自定义工具、变量赋值、MCP 调用工具、指定回复。开始组件里要加两个用户输入参数：username 和 password，这是 SQLBot 的登录凭证。再加两个会话变量：access_token 和 chat_id，用来在多次问数之间保持会话状态。

判断器的作用是检查 access_token 是否为空。如果为空，说明是第一次问数，需要先调 mcp_start 获取 token；如果不为空，说明之前已经获取过，直接调 mcp_question 就行。这个判断逻辑能避免每次问数都重新登录，减少不必要的调用。

获取 access_token 的步骤是调用 mcp_start 工具。在 MCP 调用工具组件里，mcp 服务配置填上面那段 JSON，然后获取工具列表，选择 mcp_start，传入 username 和 password 两个参数。调用结果是一个数组，数组第一个元素是响应的 JSON 字符串。接下来用一个自定义工具做标准化处理，输入参数 arg1 类型是 array，Python 代码如下：

import json def main1(arg1): json_obj = json.loads(arg1[0]) return { "token": json_obj["data"]["access_token"], "chat_id": json_obj["data"]["chat_id"] }

这段代码把 MCP 返回的数组第一个元素解析出来，提取 access_token 和 chat_id。注意 arg1[0] 这个写法，因为 MaxKB 里 MCP 调用的结果是一个数组，真正的响应在第一个元素里。如果直接写 arg1 会报类型错误。

拿到 token 和 chat_id 后，用变量赋值组件把它们分别存到两个会话变量里。赋值的时候在 result 后面加 .token 和 .chat_id，对应自定义工具返回的字段名。这一步很关键，因为后面的 mcp_question 调用需要用到这两个值，而且要用会话变量而不是直接传自定义工具的结果，否则第二次问数时 token 会丢失。

然后是调用 mcp_question 工具。同样填 MCP 服务配置，选择 mcp_question，传入三个参数：question 传用户的问题，chat_id 和 token 分别传两个会话变量。执行条件要改成“前置任一连线节点执行完，执行当前节点”，否则工作流可能卡在判断器分支上不往下走。

最后是指定回复组件，把 mcp_question 的结果展示出来。注意在 result 后面加 [0]，因为 MCP 工具返回的结果包了一层数组，真正的回复内容在第一个元素里。不加 [0] 的话，用户会看到一串带数组括号的原始数据。

AI 自动调用的配置更简单，但提示词要写清楚。开始组件同样加 username 和 password 两个参数。然后加一个 AI 对话组件，选择一个模型，模型接入用 TaoToken 的 Base URL 和 Key。系统角色可以填“BI 数据分析师”，提示词里写清楚调用逻辑：

# 回答要求： 按需调用 mcp_start 和 mcp_question 工具获取信息回答问题。 mcp_start 账号密码： username:{{global.username}} password:{{global.password}} 工具调用逻辑： 首先调用 mcp_start 工具，获取 access_token 和 chat_id， 帮我记住这两个参数，之后不要重复调用 mcp_start，直接使用即可； 然后再调用 mcp_question 工具，其中 token 和 chat_id 参数是调用 mcp_start 工具返回，question 是用户提问。 # 用户提问： {{开始.question}} # 输出要求 - 如果 mcp_question 中有图片，请直接返回图片 - 请将 mcp_question 的执行结果中的数据、SQL以及图片内容展示 - 请将 mcp_question 的执行过程在结尾进行总结 # 限制 - 不要输出MCP详细执行过程 - 生成内容不要放在 mcp_question 执行过程中 - 严格按照输出要求输出内容，不要输出MCP调用过程

这段提示词的关键是让 AI 记住 token 和 chat_id，不要重复调 mcp_start。如果不写“不要重复调用”，AI 可能会每次问数都重新登录，导致响应变慢。另外“不要输出 MCP 详细执行过程”这条限制也很重要，否则 AI 会把工具调用的中间步骤都吐出来，用户看到的是一堆调试信息而不是查询结果。

两种方案的组件对照可以看这个表：

配置完成后，建议先用工具调用方案跑通一次，确认 MCP 连接和鉴权没问题，再试 AI 自动调用。因为工具调用的每一步都是显式的，出错时容易定位是哪个组件的问题。

4. 端到端验证：一次问数请求的完整链路

配置写完后，必须做一次端到端验证，确认从 MaxKB 提问到 SQLBot 返回结果的整条链路是通的。验证的目标是：用户在 MaxKB 里输入“上个月华东区销售额是多少”，工作流调用 SQLBot 生成 SQL、执行查询、返回结果，MaxKB 展示表格或图表。

先验证 MCP 服务本身是否可达。在 MaxKB 的 MCP 调用工具组件里，填好服务配置后点“获取工具”，如果能看到 mcp_start 和 mcp_question 两个工具，说明 MCP 连接正常。如果获取工具失败，先检查 URL 和 transport，再检查 SQLBot 服务是否在运行。可以用 curl 直接测一下 MCP 端点：

curl -N http://你的服务器IP/mcp \ -H "Accept: text/event-stream"

如果返回 SSE 流或连接保持，说明服务可达。如果返回 404 或连接拒绝，说明 URL 写错或服务没启动。

然后验证模型调用。在 AI 对话组件里，模型接入用 TaoToken 的 Base URL 和 Key。可以先在模型对话页面单独测一下模型是否可用，地址是 https://taotoken.net/chat 。如果模型对话能正常返回，说明 Key 和 Base URL 没问题。如果报 401，检查 Key 是否复制完整，Base URL 是否写成了 https://taotoken.net/api 而不是其他路径。

接下来跑一次完整的工具调用流程。在 MaxKB 里新建一个对话，输入 username 和 password，然后问“上个月华东区销售额是多少”。观察工作流的执行日志：判断器应该走“access_token 为空”的分支，调用 mcp_start 获取 token，自定义工具解析出 token 和 chat_id，变量赋值存入会话变量，然后调用 mcp_question，最后指定回复展示结果。

如果一切正常，你会看到 SQLBot 返回的查询结果，通常包含三部分：生成的 SQL 语句、查询结果数据、以及可能的图表。SQL 语句类似：

SELECT region, SUM(sales_amount) AS total_sales FROM sales_records WHERE region = '华东' AND sale_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 month') AND sale_date < DATE_TRUNC('month', CURRENT_DATE) GROUP BY region;

查询结果是一个表格，显示华东区上个月的销售额汇总。如果 SQLBot 配置了图表生成，还会返回一张图片。MaxKB 的指定回复组件会把这三部分展示给用户。

再问一次“那华南区呢”，这次判断器应该走“access_token 不为空”的分支，直接调用 mcp_question，不再重新登录。如果第二次问数报 token 无效，说明会话变量没存住，检查变量赋值组件的字段名是否和自定义工具返回的字段一致。

AI 自动调用的验证类似，但观察点不同。在 AI 对话组件里输入问题后，AI 会先调 mcp_start，然后调 mcp_question，最后把结果整理成回复。如果 AI 重复调 mcp_start，说明提示词里的“不要重复调用”没生效，可以加强限制语句。如果 AI 把 MCP 调用过程也输出了，检查“不要输出 MCP 详细执行过程”这条限制是否写在提示词里。

验证通过后，建议把工作流保存为模板，方便后续复用。如果需要在多个 MaxKB 实例里部署，可以把 MCP 服务配置和提示词导出成 JSON，直接导入。

5. 常见报错排查：401、local proxy failed、reading choices

配这条链路时，报错主要集中在鉴权、网络和响应解析三类。下面按真实报错场景逐一排查。

401 Unauthorized是最常见的。出现这个报错，先检查 TaoToken 的 Key 是否复制完整，有没有多余空格。然后检查 Base URL 是否写成了 https://taotoken.net/api ，如果写成了 https://taotoken.net/api/v1 或其他路径，鉴权会失败。如果 Key 和 Base URL 都没问题，检查模型 ID 是否在 TaoToken 的模型列表里，写错模型 ID 也会返回 401。另外，如果 MCP 服务本身需要鉴权，检查 mcp_start 的 username 和 password 是否正确。

local proxy failed通常出现在 MCP 连接阶段。这个报错说明 MaxKB 无法连接到 MCP 服务地址。先检查 URL 里的 IP 和端口是否正确，如果是本地部署，确认 SQLBot 服务在运行且监听正确端口。然后检查 transport 是否写成了 sse，写成 stdio 或 http 都会导致连接失败。如果服务器有防火墙，确认端口是否开放。另外，如果 MaxKB 和 SQLBot 不在同一台机器上，确认网络是否互通，可以用 curl 从 MaxKB 所在机器测一下 MCP 端点。

reading choices 报错通常出现在解析模型响应时。这个报错说明模型返回的结构和预期不一致，可能是模型没有按格式返回，或者响应被截断。先检查提示词是否写得太复杂，导致模型输出混乱。然后检查 MaxKB 的 AI 对话组件是否打开了“返回内容”，如果没打开，后续组件拿不到响应。如果用的是流式输出，确认 MaxKB 版本是否支持。另外，如果模型返回的是 JSON 但格式不对，可以在提示词里加一句“请严格按照 JSON 格式返回”。

OAuth 相关报错如果出现，说明 MCP 服务配置了 OAuth 鉴权，但 MaxKB 的 MCP 调用工具没有传对应的 token。检查 mcp 服务配置里是否需要加 headers 或 auth 字段。如果 SQLBot 的 MCP 服务不需要 OAuth，确认配置里没有多余的鉴权参数。

token 无效或过期如果第二次问数报 token 无效，检查会话变量是否正确存储。在变量赋值组件里，确认 result 后面的字段名和自定义工具返回的字段名一致。如果字段名写错，会话变量会是空值，导致 mcp_question 调用失败。另外，如果 SQLBot 的 token 有有效期，确认在有效期内完成问数，过期后需要重新调 mcp_start。

MCP 工具列表为空如果在 MCP 调用工具组件里点“获取工具”看不到 mcp_start 和 mcp_question，说明 MCP 服务没有正确暴露工具。检查 SQLBot 的 MCP 服务是否启动，以及是否配置了正确的工具。可以用 curl 直接请求 MCP 的工具列表端点，确认返回内容。

排查时建议按顺序来：先确认 MCP 服务可达，再确认模型调用可用，最后确认工作流组件之间的数据传递正确。每一步都用最小化测试，比如先用 curl 测 MCP，再用模型对话页面测模型，最后在 MaxKB 里跑完整流程。这样出错时容易定位是哪一层的问题。

6. 把问数链路接进日常：TaoToken 的接入选择

这条链路跑通后，你可以把它扩展到更多场景。比如在 MaxKB 里加一个定时任务，每天自动问数并生成报表；或者把 SQLBot 的 MCP 服务接到其他支持 MCP 的工具里，比如 Cline、Claude Code，让编码助手也能直接查库。TaoToken 的统一 Key 和 Base URL 在这些场景里都能复用，不需要每个工具单独配模型。

如果你主要用这条链路做日常问数，调用频率不高，用按量计费的 API Key 就行。接入文档在 https://taotoken.net/doc ，里面有各语言的调用示例和模型列表。API Keys 管理在 https://taotoken.net/api-keys ，可以随时创建和撤销 Key。如果打算把问数能力集成到长期运行的 Agent 或编码工作流里，调用频率高，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan ，适合需要稳定模型接入的长期任务。

模型对话页面在 https://taotoken.net/chat ，可以用来单独测试模型是否可用，排查鉴权问题时很方便。MCP 服务的配置和 MaxKB 工作流的导出文件可以一起保存，换环境部署时直接导入，减少重复配置。

整条链路的核心是三件事：MCP 服务配置写对 URL 和 transport，模型接入用统一的 Base URL 和 Key，工作流组件之间的数据传递用会话变量保持状态。这三件事做好，MaxKB 就能从知识库问答扩展到数据库问数，SQLBot 的能力也能被更多工具调用。