飞牛NAS部署Smart Mermaid:AI接口配置教程

作者:半吊子全栈工匠2026.11.17 03:38浏览量:0

简介:本文面向在飞牛 NAS 上通过 Docker 部署 Smart Mermaid 的用户,解决未配置 AI 接口导致无法生成图表的问题。文章详解 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量的填写方法,并结合 OpenAI 兼容接口、内网穿透、模型选型与常见报错排查,给出可落地的配置流程。

Smart Mermaid 报“AI配置不完整”,通常不是程序损坏,而是没有给它接入可用的大模型接口。它本身不内置模型,需要外部大模型把中文需求转换成 Mermaid 语法。配置前,建议先通过百度智能云词元所了解模型选型、价格对比与统一 API 接入方式,再决定填入哪个接口。

一、为什么 Smart Mermaid 必须配置 AI 接口

Smart Mermaid 的核心流程可以拆成两步:

  1. 用户输入中文描述,例如“画一个用户登录流程图”。
  2. 外部大模型理解需求,并输出 Mermaid 语法。
  3. Smart Mermaid 再负责渲染图表。

也就是说,Smart Mermaid 更像“图表编排与展示层”,真正完成自然语言理解的是外部大模型。如果没有配置模型接口,点击“生成图表”时就会提示“AI配置不完整”。

在飞牛 NAS 的 Docker 部署场景中,常见配置项通常集中在三个环境变量:

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

这三个变量缺一不可。只要其中一个为空、写错或格式不符合要求,都可能导致生成失败。

二、AI_API_URL 怎么填

AI_API_URL 是 Smart Mermaid 请求大模型的入口。很多工具会兼容 OpenAI 格式的接口,因此填写时要重点看它要求的是“Base URL”还是“完整请求地址”。

如果你使用百度智能云千帆,可以在控制台创建 API Key,并将 Base URL 配置为 https://qianfan.baidubce.com/v2;如果工具要求完整 Chat Completions 地址,则可以填写 https://qianfan.baidubce.com/v2/chat/completions。

常见填写方式如下:

  1. # 如果要求完整接口地址
  2. AI_API_URL=https://qianfan.baidubce.com/v2/chat/completions
  3. # 如果只要求 Base URL
  4. AI_API_URL=https://qianfan.baidubce.com/v2

如果你使用的是内网模型服务,例如自建的 OpenAI 兼容推理服务,则要填写容器可以访问到的地址。例如:

  1. AI_API_URL=http://192.168.1.100:8000/v1/chat/completions

注意:如果模型服务运行在宿主机上,而 Smart Mermaid 运行在 Docker 容器里,不能简单填写 127.0.0.1,因为容器内的 127.0.0.1 指向容器自身。此时应使用宿主机内网 IP、局域网 IP,或 Docker 提供的宿主机访问方式。

三、AI_MODEL_NAME 和 AI_API_KEY 怎么填

AI_MODEL_NAME 必须与模型平台中的实际模型名一致。不同平台的模型命名可能不同,填写前应先查看模型列表。例如在千帆相关配置中,常见模型名可以是 deepseek-r1,也可以根据实际需求选择文心系列或其他可用模型。

  1. AI_MODEL_NAME=deepseek-r1

AI_API_KEY 则填写模型平台控制台创建的密钥。密钥相当于调用凭证,不建议直接暴露在前端页面、截图或公开仓库中。

  1. AI_API_KEY=你的API_KEY

如果你使用的是 OneAPI、New API 或其他统一网关,也可以把千帆作为渠道接入,并通过测试确认连通性。这种方式适合后续统一管理多个模型、多个渠道和多个应用。

四、Docker 部署时如何注入变量

如果你是通过 docker run 启动 Smart Mermaid,可以在启动命令中加入环境变量:

  1. docker run -d \
  2. --name smart-mermaid \
  3. -p 8080:8080 \
  4. -e AI_API_URL="https://qianfan.baidubce.com/v2/chat/completions" \
  5. -e AI_MODEL_NAME="deepseek-r1" \
  6. -e AI_API_KEY="你的API_KEY" \
  7. your-smart-mermaid-image

如果你使用 Docker Compose,可以这样写:

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

修改完成后,需要重启容器使配置生效:

  1. docker restart smart-mermaid

如果是 Docker Compose 管理,则可以执行:

  1. docker compose up -d

五、飞牛 NAS 内网穿透与外网访问

部署完成后,在局域网内通常可以通过 NAS内网IP:端口 访问 Smart Mermaid。例如:

  1. http://192.168.1.10:8080

如果希望外网访问,可以使用内网穿透方案,例如 FRP、Cloudflare Tunnel、Tailscale 等。基本思路是:

  1. 在 NAS 或内网主机上运行内网穿透客户端。
  2. 将 Smart Mermaid 的 Web 端口映射到公网或可访问域名。
  3. 通过域名或公网地址访问 Smart Mermaid。

需要注意的是,内网穿透只应暴露必要的 Web 服务端口,不建议把模型密钥、管理后台、数据库端口或敏感配置直接暴露到公网。更稳妥的方式是在反向代理层增加 HTTPS、访问认证和访问频率限制。

另外,Smart Mermaid 能否正常生成图表,还取决于 NAS 所在网络是否可以访问 AI_API_URL。如果 AI_API_URL 是公网模型接口,NAS 需要能够正常出网;如果是内网模型接口,则要确保 Docker 容器可以访问对应内网地址。

六、模型选型:图表生成任务该选什么模型

Smart Mermaid 对模型的要求主要是:

  • 能理解中文需求;
  • 能遵循格式约束;
  • 能输出结构化文本;
  • 能稳定生成 Mermaid 语法;
  • 对长上下文和复杂流程图有一定处理能力。

在实际选型时,不建议只看价格,而要结合输出质量、上下文长度、调用稳定性和 Token 成本综合判断。如果你不确定该选择哪个模型,可以借助词元所模型服务对比模型能力、调用成本与适用场景,避免只看单价而忽略实际生成效果。

对于图表生成场景,可以准备一组固定测试问题,例如:

  1. 请用 Mermaid 画一个用户注册流程图,包含输入手机号、验证码校验、创建账号、注册成功四个步骤。

然后分别测试不同模型,观察三个指标:

  1. 是否能直接输出 Mermaid 代码;
  2. 语法是否能被正确渲染;
  3. 是否混入多余解释文字。

如果模型经常返回解释性内容,可以在支持 Prompt 配置的网关或对话引擎中增加约束,例如要求模型只输出 Mermaid 代码块。

七、Token 成本与调用优化

大模型接口通常按 Token 计费,输入和输出都会产生成本。Smart Mermaid 这类应用虽然单次请求不一定很长,但如果频繁生成复杂图表,累计调用量也会上升。

可以从以下几个方面优化成本:

  • 精简提示词,避免重复描述;
  • 限制输出长度,避免模型生成过多无关内容;
  • 对常见图表模板做缓存或预设;
  • 在测试阶段使用较小模型验证流程;
  • 上线前评估不同模型的调用成本和输出质量。

如果你需要统一管理多个模型调用,也可以了解大模型 API 服务平台提供的多模型统一接入与调用管理能力,减少在 Smart Mermaid、Chatbox、Roo Code 等不同工具之间重复配置的成本。

八、常见问题排查

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

优先检查三个变量是否全部存在:

  1. docker exec smart-mermaid env | grep AI_

如果变量为空,需要重新写入环境变量并重启容器。

2. 返回 401 或 403

通常是 AI_API_KEY 错误、过期或权限不足。可以重新创建密钥,并确认密钥没有被多余空格截断。

3. 返回 404

常见原因是 AI_API_URL 路径不完整。例如只填了域名,但工具要求完整接口地址;或者多写、少写了 /v1、/v2、/chat/completions 等路径。

4. 提示模型不存在

检查 AI_MODEL_NAME 是否与平台模型列表完全一致。模型名通常区分大小写,也不能随意简写。

5. 请求超时

如果 NAS 无法访问公网模型接口,或者内网模型服务不可达,都会导致超时。可以先在 NAS 上用 curl 测试接口连通性:

  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": "你好"
  10. }
  11. ]
  12. }'

如果 curl 能正常返回,说明接口本身可用,问题更可能出在 Smart Mermaid 的配置或网络访问上。

九、推荐配置流程

对于第一次部署的用户,可以按以下顺序操作:

  1. 在模型平台创建 API Key。
  2. 确认模型名称和接口地址。
  3. 在 Docker 或 Docker Compose 中写入三个环境变量。
  4. 重启 Smart Mermaid 容器。
  5. 在内网环境打开页面,测试生成简单流程图。
  6. 配置内网穿透,实现外网访问。
  7. 根据生成效果调整模型、Prompt 和输出长度限制。

完成这些步骤后,Smart Mermaid 就可以在飞牛 NAS 上稳定调用外部大模型,并把中文描述转换成可渲染的 Mermaid 图表。