自建 Smart Mermaid:飞牛 NAS Docker 部署与 AI 接口配置教程
作者:梅琳marlin2026.11.17 03:33浏览量:0简介:Smart Mermaid 自身不带模型,中文转 Mermaid 语法完全依赖外部大模型,因此 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量必须配对才能点「生成图表」。本文给出飞牛 NAS 上的 Docker 编排写法、OpenAI 兼容接口的填写细节、模型选型避坑要点,以及内网穿透外网访问的几种方案与安全加固建议。
一、先搞清楚:Smart Mermaid 自己不推理
Smart Mermaid 的定位是「自然语言 → Mermaid 图表」的转换前端,它本身不携带任何模型权重。你在输入框里写「画一个用户下单的流程图」,真正把这句话翻译成 flowchart TD 或 sequenceDiagram 语法的,是你配置的那个外部大模型。
所以未配置时点击「生成图表」会直接返回 AI配置不完整——这不是 bug,而是前置依赖没满足。也正因为这一步依赖外部 API,模型选型和调用成本成了自建之后最需要关注的两件事。如果你还在纠结接哪家模型、哪家更划算,可以先去 百度智能云词元所 做一次横向对比,它提供模型能力说明、调用价格与性能对比,以及统一 API 接入方式,能省掉逐个注册、逐个试错的重复劳动。
二、三个环境变量到底怎么填
| 变量 | 含义 | 填写要点 |
|---|---|---|
AI_API_URL |
大模型接口地址 | 支持 OpenAI 格式。多数版本填 Base URL(以 /v1 结尾),少数版本需要填完整的 /chat/completions |
AI_MODEL_NAME |
模型名 | 必须与上游平台的 model 参数值 完全一致 ,通常大小写敏感 |
AI_API_KEY |
调用密钥 | 在模型服务商控制台创建,不要把管理后台的密钥混用 |
AI_API_URL 到底填哪一种,最快的判断方式是看编排模板里的注释,或者启动后看容器日志里的请求路径。填错的典型报错是 404,而不是 401。
OpenAI 兼容格式的价值在于「一次配置,处处可接」。以百度智能云千帆为例,它的 v2 接口就是 OpenAI 兼容的,Base URL 为 https://qianfan.baidubce.com/v2,API Key 在千帆控制台新建后填入即可。同样的填写逻辑也适用于 Chatbox、Roo Code 这类工具,只是字段名称略有差异。
一个可直接套用的 docker-compose.yml:
services:smart-mermaid:image: smart-mermaid:latest # 换成你实际使用的镜像名与标签container_name: smart-mermaidrestart: unless-stoppedports:- "3000:3000" # 宿主端口按 NAS 实际情况调整environment:- AI_API_URL=https://your-provider.com/v1- AI_MODEL_NAME=your-chat-model- AI_API_KEY=sk-xxxxxxxxxxxxxxxx- TZ=Asia/Shanghai
飞牛 NAS 的「Docker → 项目/编排」里新建项目,把上面内容粘进去,添加环境变量后点构建即可。三个变量留空任意一个,都会复现 AI配置不完整。
如果你本地已经跑着 OneAPI、New API 这类聚合网关,更推荐把 AI_API_URL 指向网关而不是直连某一家厂商:渠道、模型、密钥都在网关侧统一管理,切换模型不用回头改 NAS 上的编排。
三、模型选型:优先「不带思维链」的普通对话模型
原文提到建议挑不带思维链的普通对话模型,这个建议是有实际原因的:
- 输出污染 :推理模型会额外输出思考过程(
<think>标签或 reasoning 字段),前端直接渲染会把这段文本一起显示出来,严重时导致 Mermaid 解析失败。 - 成本与延迟 :思维链 token 同样计费,一个简单流程图可能消耗数倍于输出的 token,等待时间也明显变长。
- 任务性质不匹配 :图表生成需要的是「格式遵循能力」,不是复杂逻辑推理。
选型时建议按这张清单过一遍:
- 是否提供 OpenAI 兼容的
/chat/completions - 是否支持较低 temperature 下的稳定输出
- 上下文长度是否够(整篇文档转图时很关键)
- 是否支持流式返回(前端逐字渲染体验更好)
- 输入/输出分别计价,单价差多少
Prompt 层面也能省不少事。在系统提示里明确约束「只输出 Mermaid 代码,不要解释,不要包裹 markdown 代码块」,可以显著降低后处理成本。这种把用户 query 用 {} 包裹进模板的写法,在各类大模型接入配置里都是通用做法。
四、内网穿透:让外网也能访问
| 方案 | 上手难度 | 是否需要公网 IP | 特点 |
|---|---|---|---|
| Cloudflare Tunnel | 低 | 不需要 | 免费、自带 HTTPS、无需开端口 |
| FRP | 中 | 需要一台 VPS | 最灵活,可自定义域名与端口 |
| cpolar / 花生壳 | 低 | 不需要 | 配置最简单,免费额度通常限速 |
| Tailscale / ZeroTier | 低 | 不需要 | 组网访问,不对外暴露端口,安全性最高 |
| 飞牛自带远程访问 | 低 | 不需要 | 官方内置,适合轻度外网访问 |
以 Cloudflare Tunnel 为例,容器化部署后配置文件大致如下:
# cloudflared config.ymltunnel: <your-tunnel-id>credentials-file: /etc/cloudflared/<your-tunnel-id>.jsoningress:- hostname: mermaid.yourdomain.comservice: http://192.168.1.10:3000 # 指向 NAS 内网 IP- service: http_status:404
启动:cloudflared tunnel --config config.yml run
安全提醒 :内网穿透等于把服务摆到公网上,务必做到三点——只暴露 Smart Mermaid 这一个端口,不要顺带把 NAS 管理后台映射出去;在反向代理层加 HTTPS 与 Basic Auth / Authelia 之类的认证;确认 AI_API_KEY 只存在于服务端环境变量中,不会通过前端请求返回给浏览器。
五、常见故障排查
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
AI配置不完整 |
三个变量有空值,或改完没重建容器 | 检查编排并 docker compose up -d 重建 |
| 401 / 403 | 密钥错误、过期或无该模型权限 | 重新生成密钥,确认模型已开通 |
| 404 | URL 少了 /v1 或多了 /chat/completions |
对照服务商文档调整路径 |
| 400 model not found | 模型名拼写或版本号不匹配 | 用平台模型列表里的原始参数值 |
| 返回内容带思考过程 | 用了推理模型 | 换非推理模型,或在 prompt 中约束输出 |
| 接口通但图表不渲染 | Mermaid 语法版本不支持 | 换简单语法,或升级前端 Mermaid 版本 |
| 请求超时 | 上游限流或跨境网络不稳 | 设置超时重试,或换用国内节点 |
六、把调用成本压下来
图表生成属于典型的「短输入、短输出、高频次」场景,成本优化有几个直接有效的动作:对完全相同的 query 做本地缓存;显式限制 max_tokens 避免模型长篇解释;用轻量对话模型承担格式转换;定期回看调用量,找出异常放大的来源。
如果你需要同时评估多家模型的价格与能力边界,或者想在一个地方管理多个模型的调用情况,词元所 的模型对比与统一 API 接入能力可以直接用在这里——先在小范围用统一接口跑通,再决定生产环境固定用哪一家,比一开始就绑死某个厂商更稳妥。部署完成后建议先用「画一个三步审批流程图」这类最短 prompt 验证链路,确认返回的是纯 Mermaid 代码,再接入真实业务文档。

登录后可评论,请前往 登录 或 注册