Blume 使用指南：用纯 Markdown 快速构建 AI 就绪的文档站点（TaoToken 配置篇）

1. 为什么静态文档站需要一次 AI 接入改造Blume 是一个零配置的文档框架底层基于 Astro 和 Vite你只需要一个文件夹加几行 Markdown它就能生成带搜索、主题、SEO 的生产级文档站。它最特别的地方在于「AI 就绪」自动生成 llms.txt、支持页面 URL 追加 .md 拿原始 Markdown、内置 MCP 服务器、还能在页面里嵌一个 Ask AI 问答助手。但问题也恰好出在这里。Ask AI 和 MCP 这类能力需要一个模型端点而 Blume 默认对接的是 Vercel AI Gateway、OpenRouter 这类海外服务。对国内开发者来说直接填这些端点往往会遇到网络连通性、账号注册、计费方式不匹配等一堆琐事文档站明明已经搭好了AI 问答却迟迟跑不起来。这篇要解决的就是这一段保持你纯 Markdown 的写作体验不变只在项目配置骨架里写入 TaoToken 的统一 Key 和 API 通道让 Blume 的 Ask AI 真正连通。我会给出可复制的配置片段、本地启动后的验证请求以及几个我实际踩过的报错排查。适合已经用 Blume 或 Astro 搭好文档站、想加 AI 问答但卡在端点配置的人。TaoToken 在这里的角色很单纯它是一个 OpenAI 兼容的 API 通道你拿到一个 Key、一个 Base URL就能被 Blume 的 AI SDK 调用。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册和拿 Key 的流程后面会讲。2. TaoToken 前置拿 Key 与确认通道在动 Blume 配置之前先把「钥匙」准备好。这一步不复杂但顺序别搞反否则后面调试会分不清是 Key 的问题还是配置的问题。2.1 注册与创建 API Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册。登录后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新的 Key。创建时建议给它起个能认出来的名字比如blume-docs-askai方便以后区分是哪个项目在用。创建完成后Key 只会完整显示一次复制下来存到安全的地方。它的形态通常是一串以特定前缀开头的长字符串别直接写进会提交到 Git 的配置文件里。2.2 确认 Base URL 与模型名TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数是纯粹的接口根路径。Blume 的 Ask AI 走的是 OpenAI 兼容协议所以你需要的是「Base URL 模型名」这一对组合。模型名取决于你想用哪个模型可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里查看当前可用的列表。选一个适合文档问答的即可文档问答对推理深度要求不高响应速度和成本更值得关注。注意Base URL 填https://taotoken.net/api时不同 SDK 对路径拼接的处理不一样。有的 SDK 会自动补/v1有的不会。Blume 底层用的是 AI SDK它期望的 Base URL 通常已经包含版本段。如果连通性验证报 404优先怀疑这里改成https://taotoken.net/api/v1再试。2.3 把 Key 放进环境变量Blume 是构建工具Ask AI 的密钥必须放在服务端环境变量里绝不能出现在客户端代码或前端可见的配置中。在项目根目录创建.env文件# .env TAOTOKEN_API_KEY你的Key粘贴在这里 TAOTOKEN_BASE_URLhttps://taotoken.net/api同时确认.gitignore里有.env这一行。这一步看着基础但我见过太多人把 Key 直接写进blume.config.ts然后推到公开仓库等于把钥匙插在门上。3. 可复制配置在 Blume 骨架里写入 TaoToken 通道Blume 的配置文件是blume.config.ts用 TypeScript 写有完整的类型提示。Ask AI 的配置挂在ai字段下具体结构随版本略有差异下面给出一份可直接对照修改的骨架。3.1 基础站点配置回顾先确保你的blume.config.ts里已经有站点基本信息和部署 URL因为 Ask AI 的接口路由依赖deployment.site来生成绝对地址import { defineConfig } from blume; export default defineConfig({ title: My Docs, description: 一个使用 Blume 构建的文档站, deployment: { site: https://docs.example.com, }, content: { root: docs, }, });deployment.site如果留空本地开发时 Ask AI 的请求路径可能拼不出来验证阶段会平白多一个排查项。3.2 写入 Ask AI 的 TaoToken 配置在defineConfig里追加ai配置块。核心是把 provider 指向 OpenAI 兼容端点并把 Base URL 和 Key 从环境变量读进来import { defineConfig } from blume; export default defineConfig({ title: My Docs, description: 一个使用 Blume 构建的文档站, deployment: { site: https://docs.example.com, }, content: { root: docs, }, ai: { ask: { enabled: true, provider: openai-compatible, baseUrl: process.env.TAOTOKEN_BASE_URL, apiKey: process.env.TAOTOKEN_API_KEY, model: 你的模型名, }, }, });几个字段的含义需要说清楚。provider选 OpenAI 兼容类型这样 Blume 会用标准的/chat/completions协议发请求。baseUrl和apiKey从环境变量读避免硬编码。model填你在模型列表里选定的那个名字写错会直接返回模型不存在的错误。3.3 服务端渲染模式必须打开这是最容易漏的一步。Ask AI 和 MCP 服务器都需要服务端渲染纯静态构建默认模式下这两个功能不会工作。你需要在配置里指定一个 adapterexport default defineConfig({ // ... 其他配置 output: server, adapter: node, });adapter的可选值包括vercel、netlify、node、cloudflare。本地验证阶段用node最省事它会在本地起一个 Node 服务器Ask AI 的接口路由能正常响应。部署到 Vercel 或 Netlify 时再换成对应平台的值。提示如果你暂时只想验证连通性、不打算立刻上服务端渲染也可以先只配ai.ask然后跑blume dev。开发模式下 Blume 会临时启用服务端能力接口能通但blume build出来的静态产物里 Ask AI 不会生效。验证和生产是两回事别混淆。3.4 如果用的是 config.toml 风格部分 Astro 生态的项目习惯用astro.config.toml或类似的 TOML 骨架。Blume 本身主推blume.config.ts但如果你在 Eject 之后拿到了独立 Astro 项目配置会落到astro.config.mjs里。此时 TaoToken 的接入点变成 Astro 的集成配置思路一样把 Base URL 和 Key 通过环境变量注入指向 OpenAI 兼容端点。TOML 场景下对应写法是[ai.ask] enabled true provider openai-compatible base_url https://taotoken.net/api model 你的模型名Key 依然走环境变量不要写进 TOML 文件。4. 验证请求本地启动后确认连通配置写完不代表通了必须发一次真实请求确认。这一步是整个流程里最有价值的部分因为报错信息会直接告诉你卡在哪。4.1 启动开发服务器在项目根目录运行npx blume dev启动后访问http://localhost:4321。如果配置里开了服务端渲染Blume 会同时启动接口路由。你可以在页面上找到 Ask AI 的入口通常在右下角或侧边栏。4.2 用 curl 直接打接口比起在页面上点按钮我更推荐先用 curl 直接验证通道这样能把「Blume 前端问题」和「API 通道问题」分开。Blume 的 Ask AI 接口路径通常是/api/ask或类似路由具体以你启动日志里打印的为准。假设是/api/askcurl -X POST http://localhost:4321/api/ask \ -H Content-Type: application/json \ -d {messages:[{role:user,content:这个文档站是做什么的}]}如果通道正常你会收到一段流式或完整的 JSON 响应内容是基于你docs/目录里 Markdown 生成的回答。这一步成功说明 TaoToken 的 Key、Base URL、模型名三者都对上了。4.3 直接验证 TaoToken 通道本身如果上面的请求报错先绕过 Blume直接打 TaoToken 的接口确认通道本身没问题curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }这个请求返回正常就说明 Key 和 Base URL 没问题问题出在 Blume 的配置层。返回 401 是 Key 错返回 404 是 Base URL 路径错返回模型不存在是模型名错。三种错误对应三个不同的修复动作别混着改。4.4 成功结果长什么样通道打通后你在文档页面里问「怎么配置搜索」Ask AI 会基于你docs/里的实际内容回答而不是编造。同时blume build之后/llms.txt和/llms-full.txt会正常生成页面 URL 追加.md能拿到原始 Markdown。这几个信号同时出现说明文档站已经从静态内容升级成 AI 就绪状态而你的写作流程还是纯 Markdown一点没变。5. 本篇常见错排查下面这几个是我在配置过程中实际遇到或见别人问得最多的按出现频率排序。报错一404 Not Found路径拼错。最常见。TaoToken 的 Base URL 是https://taotoken.net/api但 AI SDK 可能期望https://taotoken.net/api/v1。两个都试一下看哪个返回正常。判断方法就是上面 4.3 的 curl把两个路径分别打一遍。报错二401 UnauthorizedKey 没读到。大概率是环境变量没加载。Blume 读的是process.env.TAOTOKEN_API_KEY如果你在.env里写了但没重启 dev server进程里还是旧值。改完.env必须重启。另外确认.env在项目根目录不是docs/里面。报错三模型不存在。模型名拼写错误或者你选的模型当前不可用。去模型对话页面核对一下准确名称注意大小写和连字符。有些模型名带版本号后缀少一段就找不到。报错四Ask AI 入口不显示。检查ai.ask.enabled是否为true以及是否用了服务端渲染模式。纯静态构建下入口不会渲染。本地blume dev能看到但blume build后看不到就是这个原因。报错五回答内容和文档无关。说明检索层没拿到你的 Markdown。确认content.root指向的目录正确且docs/里有实际的.md或.mdx文件。Blume 的 Ask AI 是基于文档内容做 grounding 的内容目录空了它就只能瞎答。报错六构建时报 adapter 相关错误。output: server和adapter必须成对出现。只写了一个会报错。本地用node部署平台用对应值。6. 把 AI 能力接进你的 Markdown 工作流配置跑通之后日常使用其实没什么额外负担。你还是写 MarkdownBlume 负责把它变成可被 AI 读取的结构化内容。这里给几个让这套组合更顺手的做法。第一把llms.txt当成对外接口来维护。它自动生成但页面摘要的质量取决于你 frontmatter 里的description写得清不清楚。花点时间把每个页面的 description 写准AI 代理读到的索引质量会明显提升。第二MCP 服务器接进 Claude Code 或 Cursor 之后你在编辑器里就能直接搜自己的文档不用切浏览器。连接命令是claude mcp add --transport http your-docs https://docs.example.com/mcp把域名换成你的。这个能力同样依赖服务端渲染部署时别忘了 adapter。第三如果你打算长期在文档项目里做 AI 相关的编码和 Agent 调试可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对的是持续性的编码场景和单次问答的计费方式不太一样。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到协议细节问题时翻这里比猜快。最后说一个我自己的习惯每次改完blume.config.ts里的 AI 配置先跑 4.3 那条 curl 确认通道再跑blume dev看页面。两步分开出问题时能立刻定位是通道挂了还是配置写错了。这个顺序帮我省了不少来回折腾的时间。