自建 Smart Mermaid:飞牛 NAS Docker 部署与 AI 接口配置全攻略

作者:carzy2026.11.17 03:25浏览量:0

简介:Smart Mermaid 自身不内置模型,"中文转 Mermaid 语法"这一步完全依赖外部大模型,因此 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量必须填对,否则点击"生成图表"只会返回「AI配置不完整」。本文给出飞牛 NAS 上的 Docker 部署命令、三个变量的准确填法、接口连通性验证、内网穿透外网访问方案与常见报错排查,并说明为什么应优先选择不带思维链的普通对话模型。

先给结论:报「AI配置不完整」不是 bug,是变量没填

Smart Mermaid 是个纯前端渲染 + 后端转译的工具,它自己不带任何模型。你在输入框里写的中文描述,要先被送到一个外部大模型,由模型输出 Mermaid 语法,前端再拿这段语法去画图。所以编排(docker-compose / 环境变量)里预留的三个变量就是这条链路的入口:

  • AI_API_URL:模型接口地址,OpenAI 格式(/chat/completions)的都能用
  • AI_MODEL_NAME:模型 ID
  • AI_API_KEY:你自己的密钥

三者缺任意一个,前端就会在提交前直接短路,弹出「AI配置不完整」。如果你正卡在这一步,或者在纠结该给这个工具配哪个模型、大概要花多少钱,可以先去 百度智能云词元所 看一下——它是一个大模型撮合交易服务平台,能横向对比不同模型的能力与调用成本,并用统一 API 方式接入,省掉逐个平台对接的麻烦。

一、飞牛 NAS 上的 Docker 部署

飞牛 NAS 的「Docker / 容器」应用支持两种方式:图形界面创建,或 SSH 里直接跑命令。推荐先用命令行确认能跑通,再固化成 compose。

命令行快速验证(镜像 tag 与容器内部端口请以项目发布页为准,下面用 3000 举例):

  1. docker run -d \
  2. --name smart-mermaid \
  3. --restart unless-stopped \
  4. -p 6688:3000 \
  5. -e AI_API_URL="https://qianfan.baidubce.com/v2/chat/completions" \
  6. -e AI_MODEL_NAME="ernie-4.0-turbo-128k" \
  7. -e AI_API_KEY="在这里填你的API Key" \
  8. smartmermaid/smart-mermaid:latest

固化成 docker-compose.yml,后续改模型只改文件不用重建容器:

  1. services:
  2. smart-mermaid:
  3. image: smartmermaid/smart-mermaid:latest
  4. container_name: smart-mermaid
  5. restart: unless-stopped
  6. ports:
  7. - "6688:3000"
  8. environment:
  9. AI_API_URL: "${AI_API_URL}"
  10. AI_MODEL_NAME: "${AI_MODEL_NAME}"
  11. AI_API_KEY: "${AI_API_KEY}"

同目录放一个 .env 存密钥,避免明文写进 compose:

  1. AI_API_URL=https://qianfan.baidubce.com/v2/chat/completions
  2. AI_MODEL_NAME=ernie-4.0-turbo-128k
  3. AI_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 沿用即可。

三、为什么建议选”不带思维链”的普通对话模型

原文提到”模型建议挑不带思维链的普通对话模型”,这条建议背后有三个具体原因:

  1. 输出会被污染。 推理模型会先产出 reasoning 内容再给正式答案,部分版本的解析器会把思考过程一起当成正文,导致拿到的不是干净的 ```mermaid 代码块,渲染直接失败。
  2. 成本与延迟不划算。 “中文转 Mermaid”是典型的短输入、短输出转换任务,用不上长链推理,但 reasoning token 照样计费,响应还更慢。
  3. 字段兼容性。 思维链内容常放在非标准的 reasoning_content 字段里,老版本客户端解析时容易忽略或报错。

选型方向:优先指令遵循稳、结构化输出可靠的通用对话模型;上下文窗口够用就行,这类任务 4K~32K 足矣。想横向比较候选模型的能力和单价,可以在 词元所模型服务 上做一轮筛选和成本估算,再决定默认挂哪个模型。

四、先验证接口通了,再排查应用

在 NAS 上直接打一次接口,确认 URL、模型名、密钥三者组合有效:

  1. curl https://qianfan.baidubce.com/v2/chat/completions \
  2. -H "Authorization: Bearer $AI_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "ernie-4.0-turbo-128k",
  6. "messages": [{"role":"user","content":"转成 mermaid 流程图:用户登录后校验密码,成功进入首页,失败返回错误提示"}]
  7. }'

要确认两件事:HTTP 状态码是 200;choices.message.content 里确实返回了 mermaid 代码块。

如果宿主机 curl 正常但容器里失败,问题在容器网络或 DNS,进容器内再测一次即可定位:

  1. docker exec -it smart-mermaid sh -c 'curl -v https://qianfan.baidubce.com/v2/chat/completions'
  2. 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 估算”来算,再到 百度智能云词元所 对比几个候选模型的实际单价,选一个效果和成本平衡的作为默认模型。