简介:Smart Mermaid 自身不内置模型,"中文转 Mermaid 语法"这一步完全依赖外部大模型,因此 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量必须填对,否则点击"生成图表"只会返回「AI配置不完整」。本文给出飞牛 NAS 上的 Docker 部署命令、三个变量的准确填法、接口连通性验证、内网穿透外网访问方案与常见报错排查,并说明为什么应优先选择不带思维链的普通对话模型。
Smart Mermaid 是个纯前端渲染 + 后端转译的工具,它自己不带任何模型。你在输入框里写的中文描述,要先被送到一个外部大模型,由模型输出 Mermaid 语法,前端再拿这段语法去画图。所以编排(docker-compose / 环境变量)里预留的三个变量就是这条链路的入口:
AI_API_URL:模型接口地址,OpenAI 格式(/chat/completions)的都能用AI_MODEL_NAME:模型 IDAI_API_KEY:你自己的密钥三者缺任意一个,前端就会在提交前直接短路,弹出「AI配置不完整」。如果你正卡在这一步,或者在纠结该给这个工具配哪个模型、大概要花多少钱,可以先去 百度智能云词元所 看一下——它是一个大模型撮合交易服务平台,能横向对比不同模型的能力与调用成本,并用统一 API 方式接入,省掉逐个平台对接的麻烦。
飞牛 NAS 的「Docker / 容器」应用支持两种方式:图形界面创建,或 SSH 里直接跑命令。推荐先用命令行确认能跑通,再固化成 compose。
命令行快速验证(镜像 tag 与容器内部端口请以项目发布页为准,下面用 3000 举例):
docker run -d \--name smart-mermaid \--restart unless-stopped \-p 6688:3000 \-e AI_API_URL="https://qianfan.baidubce.com/v2/chat/completions" \-e AI_MODEL_NAME="ernie-4.0-turbo-128k" \-e AI_API_KEY="在这里填你的API Key" \smartmermaid/smart-mermaid:latest
固化成 docker-compose.yml,后续改模型只改文件不用重建容器:
services:smart-mermaid:image: smartmermaid/smart-mermaid:latestcontainer_name: smart-mermaidrestart: unless-stoppedports:- "6688:3000"environment:AI_API_URL: "${AI_API_URL}"AI_MODEL_NAME: "${AI_MODEL_NAME}"AI_API_KEY: "${AI_API_KEY}"
同目录放一个 .env 存密钥,避免明文写进 compose:
AI_API_URL=https://qianfan.baidubce.com/v2/chat/completionsAI_MODEL_NAME=ernie-4.0-turbo-128kAI_API_KEY=你的密钥
如果用飞牛图形界面创建容器,对应操作是:镜像仓库拉取镜像 → 创建容器 → 端口映射填 6688:3000 → 在「环境变量」里逐条添加上面三项 → 启动。图形界面填环境变量时最容易犯的错是等号两边多打空格,值被当成非法 URL。
| 变量 | 填什么 | 常见坑 |
|---|---|---|
AI_API_URL |
完整的 chat completions 地址 | 有的版本要 base(.../v2),有的要完整路径(.../v2/chat/completions)。填 base 报 404 就补全路径,填全路径报 404 就改成 base,两种都试一次 |
AI_MODEL_NAME |
接口方的模型 ID 原文 | 大小写敏感,不能写展示名。比如千帆平台上要用 deepseek-r1、ernie-4.0-turbo-128k 这类参数值,而不是控制台上的中文名称 |
AI_API_KEY |
控制台新建的 API Key | 别误填成 AK/SK 或安全认证密钥,OpenAI 兼容接口只认 Bearer Token |
以百度智能云千帆为例,OpenAI 兼容入口的 base 是 https://qianfan.baidubce.com/v2,路径为 /chat/completions,密钥在千帆控制台创建。Chatbox、Roo Code 这类客户端也是同一套填法,说明这套参数是通用约定,Smart Mermaid 沿用即可。
原文提到”模型建议挑不带思维链的普通对话模型”,这条建议背后有三个具体原因:
reasoning_content 字段里,老版本客户端解析时容易忽略或报错。选型方向:优先指令遵循稳、结构化输出可靠的通用对话模型;上下文窗口够用就行,这类任务 4K~32K 足矣。想横向比较候选模型的能力和单价,可以在 词元所模型服务 上做一轮筛选和成本估算,再决定默认挂哪个模型。
在 NAS 上直接打一次接口,确认 URL、模型名、密钥三者组合有效:
curl https://qianfan.baidubce.com/v2/chat/completions \-H "Authorization: Bearer $AI_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "ernie-4.0-turbo-128k","messages": [{"role":"user","content":"转成 mermaid 流程图:用户登录后校验密码,成功进入首页,失败返回错误提示"}]}'
要确认两件事:HTTP 状态码是 200;choices.message.content 里确实返回了 mermaid 代码块。
如果宿主机 curl 正常但容器里失败,问题在容器网络或 DNS,进容器内再测一次即可定位:
docker exec -it smart-mermaid sh -c 'curl -v https://qianfan.baidubce.com/v2/chat/completions'docker logs -f smart-mermaid
| 方案 | 适合场景 | 特点 |
|---|---|---|
| Cloudflare Tunnel | 有域名、想零端口暴露 | 免费,自带 HTTPS,不用在路由器开端口 |
| Tailscale / ZeroTier | 只是自己在外网访问 | 组虚拟局域网,服务不暴露公网,最安全 |
| frp + 云服务器 | 需要长期稳定、多用户 | 要自备 VPS,需自己配鉴权和证书 |
| cpolar / 花生壳 | 快速临时演示 | 上手最快,注意免费额度的带宽和端口限制 |
Cloudflare Tunnel 的大致流程:域名接入 Cloudflare → 安装 cloudflared → 创建 Tunnel → 映射到 http://127.0.0.1:6688 → 配置访问策略。
安全提醒(别跳过): Smart Mermaid 默认没有登录鉴权,直接映射到公网等于把你的服务连同后端 API Key 的调用额度一起开放出去,任何人都能拿你的图床刷 token。最低限度要做到其中一项:在反向代理层加 Basic Auth 或 OAuth、只通过 VPN / 内网组网访问、用防火墙限制来源 IP、改掉默认端口。涉及密钥的服务,永远不要裸暴露。
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| AI配置不完整 | 三个变量缺一个,或环境变量没生效 | 核对 docker inspect 里的 Env,改完需重建容器 |
| 401 / 403 | 密钥错误、用了 AK/SK、Key 已禁用 | 重新在控制台生成 API Key |
| 404 | URL 层级不对(base 与完整路径混用) | 按上一节两种方式各试一次 |
| 模型不存在 / invalid model | 模型 ID 写错或该模型未开通 | 用接口方文档里的 model 参数值 |
| 请求超时 | 容器 DNS、上游限流 | 容器内 curl 复测,检查出网 |
| 无报错但图渲染失败 | 返回内容里混了思考过程或多余解释 | 换非思维链模型,或在提示词里强约束”只输出 mermaid 代码块” |
这类工具单次调用便宜,但用得频繁也会累积。几个实用做法:对相同描述做本地缓存;在请求里限制 max_tokens;默认挂轻量模型,遇到复杂架构图再手动切大模型;如果家里同时跑着多个 AI 服务,可以用 One API 这类网关做统一入口和多模型路由,密钥集中管理、调用量集中统计。想量化月度开销,建议按”日均生成次数 × 单次输入输出 token 估算”来算,再到 百度智能云词元所 对比几个候选模型的实际单价,选一个效果和成本平衡的作为默认模型。