logo

飞牛NAS自建Smart Mermaid部署与AI接口配置教程

作者:搬砖的石头2026.11.17 03:26浏览量:0

简介:本文围绕飞牛 NAS 使用 Docker 自建 Smart Mermaid 并实现外网访问,重点解决未配置 AI 接口导致“AI配置不完整”的问题,给出环境变量、OpenAI 兼容接口、内网穿透与安全注意事项,并介绍如何通过词元所辅助模型选型与接入。

Smart Mermaid 本身不内置大模型,它负责把用户输入转换为图表结构,而“把中文需求翻译成 Mermaid 语法”这一步需要调用外部大模型完成。因此,在飞牛 NAS 上完成 Docker 部署后,如果没有配置 AI 接口,点击“生成图表”就会提示“AI配置不完整”。如果你刚开始准备模型接入,可以先通过 百度智能云词元所 了解模型选型、价格对比和统一 API 接入方式,再决定 Smart Mermaid 后接哪类模型服务。

一、部署前准备

在飞牛 NAS 上部署 Smart Mermaid,通常需要满足以下条件:

  • 已安装 Docker 或 Docker Compose。
  • 已创建用于存放配置文件的目录,例如 /vol1/docker/smart-mermaid。
  • 已准备一个 OpenAI 兼容的大模型接口。
  • 如需外网访问,已准备内网穿透方案,例如 frp、Cloudflare Tunnel、Tailscale 等。

Smart Mermaid 的核心不是“画图引擎”,而是“AI 翻译层”。也就是说,它需要把自然语言描述交给大模型,再由大模型输出 Mermaid 代码。因此,AI 接口是否可用,直接决定 Smart Mermaid 能否正常工作。

二、Docker 部署 Smart Mermaid

下面以 Docker Compose 为例。实际部署时,请将镜像名替换为 Smart Mermaid 项目发布的实际镜像。

  1. services:
  2. smart-mermaid:
  3. image: your-smart-mermaid-image
  4. container_name: smart-mermaid
  5. restart: unless-stopped
  6. ports:
  7. - "3000:3000"
  8. environment:
  9. - AI_API_URL=https://qianfan.baidubce.com/v2/chat/completions
  10. - AI_MODEL_NAME=deepseek-r1
  11. - AI_API_KEY=你的API_KEY

启动命令:

  1. cd /vol1/docker/smart-mermaid
  2. docker compose up -d

启动后,可以通过 NAS 内网地址访问:

  1. http://NAS内网IP:3000

如果页面能打开,但生成图表失败,优先检查三个环境变量:AI_API_URL、AI_MODEL_NAME、AI_API_KEY。

三、AI 接口配置:三个关键变量

Smart Mermaid 编排中的三个变量分别对应:

变量 作用 示例
AI_API_URL 大模型接口地址 https://qianfan.baidubce.com/v2/chat/completions
AI_MODEL_NAME 模型名称 deepseek-r1
AI_API_KEY 调用密钥 控制台创建的 API Key

这里需要注意:不同程序对“接口地址”的定义可能不同。有的程序要求填写 Base URL,有的程序要求填写完整的 Chat Completions 地址。

如果 Smart Mermaid 要求填写 Base URL,可以填写:

  1. https://qianfan.baidubce.com/v2

如果要求填写完整请求地址,则可以填写:

  1. https://qianfan.baidubce.com/v2/chat/completions

百度智能云千帆提供 OpenAI 兼容接入方式,在 Chatbox、Roo Code、One API 等工具中都可以看到类似的 Base URL 配置方式。因此,Smart Mermaid 只要支持 OpenAI 格式接口,就可以接入这类服务。

四、模型选择:优先普通对话模型

原始需求中提到,模型建议选择不带思维链的普通对话模型,这个建议非常关键。

Smart Mermaid 需要的是“直接输出 Mermaid 代码”的模型,而不是先长篇分析、再给出结果的推理型模型。如果模型返回内容包含大量解释、思考过程或 Markdown 说明,Smart Mermaid 可能无法正确解析。

建议遵循以下原则:

  1. 优先选择普通对话模型。
  2. 避免选择容易输出长推理过程的模型。
  3. 如果模型支持系统提示词,可要求其只输出 Mermaid 代码。
  4. 测试时先用简单需求,例如“绘制用户登录流程图”。

一个简单的接口测试示例:

  1. curl https://qianfan.baidubce.com/v2/chat/completions \
  2. -H "Authorization: Bearer 你的API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "deepseek-r1",
  6. "messages": [
  7. {
  8. "role": "user",
  9. "content": "请用 Mermaid 绘制用户登录流程,只输出 Mermaid 代码。"
  10. }
  11. ]
  12. }'

如果返回内容中包含 ```mermaid 代码块,说明接口基本可用。若返回大量解释文本,可以在 Smart Mermaid 的提示词或模型参数中增加约束,例如要求“只输出 Mermaid 语法,不要解释”。

如果你不确定应该选择哪类模型,可以通过 词元所模型服务 对比不同模型的能力、调用成本和适用场景,再选择与 Smart Mermaid 匹配的模型。

五、内网穿透:让外网访问 NAS 上的 Smart Mermaid

如果只在局域网内使用,直接通过 NAS内网IP:3000 访问即可。但如果需要在外面访问,就要配置内网穿透。

以常见的 frp 为例,服务端需要部署在有公网 IP 的服务器上,客户端部署在飞牛 NAS 内。

frpc.toml 示例:

  1. serverAddr = "你的公网服务器IP"
  2. serverPort = 7000
  3. [[proxies]]
  4. name = "smart-mermaid"
  5. type = "tcp"
  6. localIP = "127.0.0.1"
  7. localPort = 3000
  8. remotePort = 6000

启动客户端:

  1. ./frpc -c ./frpc.toml

之后可以通过:

  1. http://你的公网服务器IP:6000

访问 Smart Mermaid。

如果需要更安全,建议不要直接暴露 HTTP 明文端口,而是配合反向代理、HTTPS 证书和访问认证使用。例如使用 Nginx、Caddy 或 NAS 自带反向代理功能,将域名请求转发到 Smart Mermaid 容器。

六、常见问题排查

1. 提示“AI配置不完整”

检查以下三项:

  • AI_API_URL 是否为空。
  • AI_MODEL_NAME 是否填写了有效模型名。
  • AI_API_KEY 是否正确,是否包含多余空格。

2. 接口返回 401 或鉴权失败

通常是 API Key 错误或已失效。可以到对应大模型平台控制台重新创建密钥,并确认密钥没有被截断。

3. 图表生成失败,但接口能返回内容

可能是模型返回了非 Mermaid 内容。建议检查模型输出是否包含解释文字、思维过程或代码块标记。可以在提示词中明确要求:

  1. 只输出 Mermaid 代码,不要输出解释,不要输出思考过程。

4. 外网访问 502 或无法连接

检查:

  • frp 客户端是否在线。
  • NAS 本地端口是否正确。
  • 防火墙是否放行对应端口。
  • 反向代理是否正确指向 Smart Mermaid 容器。

七、统一接入与后续管理

如果你的 NAS 上不仅部署了 Smart Mermaid,还接入了多个 AI 应用,例如 Chatbox、Roo Code、One API 或其他自动化工具,那么统一接口管理会很有价值。One API 这类工具可以作为统一网关,将不同模型服务封装成统一接口,方便多个应用复用。

在模型接入阶段,建议先明确三个问题:

  1. 这个应用需要“生成代码”还是“多轮对话”?
  2. 是否需要长上下文?
  3. 调用成本是否在可接受范围内?

对于 Smart Mermaid 这种图表生成场景,模型输出稳定性比参数规模更重要。一个能稳定输出 Mermaid 代码的普通对话模型,往往比复杂推理模型更适合。

后续如需统一管理多模型调用,可借助 大模型 API 服务平台 进行接入与调用管理,减少多个应用重复配置接口的成本。

发表评论

活动