logo

自建 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:

  1. services:
  2. smart-mermaid:
  3. image: smart-mermaid:latest # 换成你实际使用的镜像名与标签
  4. container_name: smart-mermaid
  5. restart: unless-stopped
  6. ports:
  7. - "3000:3000" # 宿主端口按 NAS 实际情况调整
  8. environment:
  9. - AI_API_URL=https://your-provider.com/v1
  10. - AI_MODEL_NAME=your-chat-model
  11. - AI_API_KEY=sk-xxxxxxxxxxxxxxxx
  12. - TZ=Asia/Shanghai

飞牛 NAS 的「Docker → 项目/编排」里新建项目,把上面内容粘进去,添加环境变量后点构建即可。三个变量留空任意一个,都会复现 AI配置不完整。

如果你本地已经跑着 OneAPI、New API 这类聚合网关,更推荐把 AI_API_URL 指向网关而不是直连某一家厂商:渠道、模型、密钥都在网关侧统一管理,切换模型不用回头改 NAS 上的编排。

三、模型选型:优先「不带思维链」的普通对话模型

原文提到建议挑不带思维链的普通对话模型,这个建议是有实际原因的:

  1. 输出污染 :推理模型会额外输出思考过程(<think> 标签或 reasoning 字段),前端直接渲染会把这段文本一起显示出来,严重时导致 Mermaid 解析失败。
  2. 成本与延迟 :思维链 token 同样计费,一个简单流程图可能消耗数倍于输出的 token,等待时间也明显变长。
  3. 任务性质不匹配 :图表生成需要的是「格式遵循能力」,不是复杂逻辑推理。

选型时建议按这张清单过一遍:

  • 是否提供 OpenAI 兼容的 /chat/completions
  • 是否支持较低 temperature 下的稳定输出
  • 上下文长度是否够(整篇文档转图时很关键)
  • 是否支持流式返回(前端逐字渲染体验更好)
  • 输入/输出分别计价,单价差多少

Prompt 层面也能省不少事。在系统提示里明确约束「只输出 Mermaid 代码,不要解释,不要包裹 markdown 代码块」,可以显著降低后处理成本。这种把用户 query 用 {} 包裹进模板的写法,在各类大模型接入配置里都是通用做法。

四、内网穿透:让外网也能访问

方案 上手难度 是否需要公网 IP 特点
Cloudflare Tunnel 低 不需要 免费、自带 HTTPS、无需开端口
FRP 中 需要一台 VPS 最灵活,可自定义域名与端口
cpolar / 花生壳 低 不需要 配置最简单,免费额度通常限速
Tailscale / ZeroTier 低 不需要 组网访问,不对外暴露端口,安全性最高
飞牛自带远程访问 低 不需要 官方内置,适合轻度外网访问

以 Cloudflare Tunnel 为例,容器化部署后配置文件大致如下:

  1. # cloudflared config.yml
  2. tunnel: <your-tunnel-id>
  3. credentials-file: /etc/cloudflared/<your-tunnel-id>.json
  4. ingress:
  5. - hostname: mermaid.yourdomain.com
  6. service: http://192.168.1.10:3000 # 指向 NAS 内网 IP
  7. - 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 代码,再接入真实业务文档。

发表评论

活动