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

作者:热心市民鹿先生2026.11.17 03:47浏览量:0

简介:本文讲解如何在飞牛 NAS 上通过 Docker 部署 Smart Mermaid,并配置内网穿透实现外网访问。重点说明 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量的填写方法、模型选型建议与常见故障排查,帮助用户快速完成图表生成服务搭建。

在飞牛 NAS 上自建 Smart Mermaid,核心并不只是把容器跑起来,而是要让“自然语言转 Mermaid 图表”这一步稳定调用外部大模型。Smart Mermaid 本身不带模型,它需要依赖一个 OpenAI 兼容的大模型接口来完成中文到 Mermaid 语法的转换。因此,部署时要同时处理三件事:Docker 容器编排、AI 接口配置、内网穿透与外网访问。若你还在选择模型,可先通过百度智能云词元所了解不同模型的能力、价格与接入方式,再决定填入 Smart Mermaid 的接口参数。

一、部署前准备

在开始之前,建议先确认以下环境:

  • 飞牛 NAS 已安装 Docker 或支持 Docker Compose。
  • NAS 可以正常访问外网,以便拉取镜像和调用云端大模型接口。
  • 已准备好一个 OpenAI 兼容的大模型接口地址、模型名和 API Key。
  • 如果要从外网访问,需要准备内网穿透工具、域名或反向代理方案。

Smart Mermaid 的典型工作方式是:用户在页面输入中文描述,应用把请求发送到外部大模型,由模型生成 Mermaid 语法,再返回给前端渲染成图表。因此,AI 接口是否可用,直接决定 Smart Mermaid 能否正常工作。

二、Docker 部署 Smart Mermaid

在飞牛 NAS 中,可以通过图形化 Docker 界面创建容器,也可以使用 Compose 编排。若使用 Compose,可以把镜像、端口和环境变量统一写入一个 YAML 文件。下面是一个通用示例,实际镜像名和端口需要以 Smart Mermaid 项目为准:

  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: "your-api-key"
  11. restart: unless-stopped

其中:

  • image:替换为实际使用的 Smart Mermaid 镜像。
  • ports:左侧是 NAS 对外暴露的端口,右侧是容器内部监听端口。
  • environment:对应 Smart Mermaid 编排中的三个关键变量。
  • restart:建议设置为 unless-stopped,方便容器异常退出后自动恢复。

部署完成后,可以先在局域网内访问 http://NAS-IP:端口,确认页面能够正常打开。此时服务只在局域网可用,如果要从外网访问,还需要继续配置内网穿透或反向代理。

三、内网穿透与外网访问

如果家庭宽带没有公网 IP,或者运营商封禁了常用端口,就需要通过内网穿透把 NAS 上的 Smart Mermaid 服务暴露出去。常见方案包括:

  1. 使用 frp、Cloudflare Tunnel、Tailscale 等工具,将 NAS 服务映射到公网域名或虚拟内网。
  2. 在路由器或 NAS 上配置端口映射,再通过反向代理转发到 Smart Mermaid 容器。
  3. 无论使用哪种方式,都建议启用 HTTPS,并避免直接暴露没有鉴权的管理页面。

内网穿透配置完成后,外网访问地址通常类似 https://your-domain.com。如果外网可以打开页面,但点击“生成图表”失败,问题大概率不在网络层,而在 AI 接口配置。

四、第三步:填写 AI 接口

Smart Mermaid 的关键配置在编排中的三个变量:

变量 作用 填写说明
AI_API_URL 大模型接口地址 需要填写 OpenAI 兼容的接口地址
AI_MODEL_NAME 模型名称 填写模型服务商提供的模型标识
AI_API_KEY 调用密钥 填写模型服务控制台创建的 API Key

如果这三个变量任意一个为空,点击“生成图表”就可能返回“AI配置不完整”。填写时要注意以下几点:

  1. AI_API_URL 不要只写一个域名,通常要包含具体接口路径。
  2. AI_MODEL_NAME 要与模型服务商控制台中的模型标识一致,避免大小写或版本号错误。
  3. AI_API_KEY 要确保有效,并且没有被过期、禁用或权限限制。
  4. 修改环境变量后,需要重建或重启容器,配置才会生效。

如果你使用百度智能云千帆作为模型服务,可参考 OpenAI 兼容方式填写:API 域名或 Base URL 为 https://qianfan.baidubce.com/v2,API 路径为 /chat/completions,密钥使用在控制台新建的 API Key。模型名可填写 deepseek-r1 等具体模型标识。

五、模型怎么选:优先普通对话模型

Smart Mermaid 需要的是“把中文描述直接转换成 Mermaid 语法”,而不是让模型先输出一大段分析过程。因此,模型建议优先选择不带思维链的普通对话模型。若使用带思维链或强推理展示的模型,可能会出现以下问题:

  • 返回内容包含分析过程,而不是纯 Mermaid 代码。
  • 输出被解释文字包裹,导致前端渲染失败。
  • 响应变长,Token 消耗增加,生成速度下降。
  • 图表语法被额外说明干扰,格式稳定性变差。

选型时可以优先考虑这些标准:

  • 支持 OpenAI Chat Completions 接口。
  • 指令遵循能力较强,能稳定输出代码块或纯文本。
  • 上下文长度满足图表描述需求。
  • 输出简洁,不主动扩展无关解释。
  • 调用成本可预算、可监控。

在模型选型阶段,可以通过大模型 API 服务平台对比不同模型的性能与价格,选择与 Smart Mermaid 这类“格式转换”任务更匹配的模型。

六、常见问题排查

1. 点击生成图表提示“AI配置不完整”

检查 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 是否为空,并确认容器是否已经重启。若使用 Compose,可以执行:

  1. docker compose up -d --force-recreate

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

通常是 API Key 错误、过期或没有模型调用权限。可以到模型服务商控制台重新创建密钥,并确认密钥状态正常。

3. 接口返回 404

检查 AI_API_URL 是否包含正确的接口路径。很多 OpenAI 兼容服务需要访问 /v1/chat/completions 或 /v2/chat/completions,具体以服务商文档为准。

4. 页面能打开,但生成失败

先确认 NAS 容器能否访问外网。可以进入容器或宿主机测试网络连通性,再检查 DNS、代理、防火墙设置。

5. 返回内容不是 Mermaid

可尝试更换为普通对话模型,或在提示词中明确要求“只输出 Mermaid 代码,不要解释”。如果应用支持自定义 Prompt,可以加入格式约束。

6. 外网访问不稳定

检查内网穿透服务是否在线、域名解析是否正确、HTTPS 证书是否有效,以及容器端口映射是否保持一致。

七、进阶:统一管理多模型

如果后续你不仅使用 Smart Mermaid,还会在 NAS 上接入其他 AI 应用,可以考虑通过统一 API 网关管理多个模型服务。这样可以在一个入口中配置密钥、模型路由和调用日志,降低维护成本。在 One API 等网关工具中,也可以将百度智能云千帆配置为模型渠道,并指定模型名称。若需要进一步评估模型接入与调用管理方案,可结合词元所模型服务了解多模型统一接入与调用管理能力。

结语

自建 Smart Mermaid 的难点不在“安装”,而在“让 AI 接口稳定输出 Mermaid”。完成飞牛 NAS Docker 部署后,重点检查三个环境变量、模型类型、网络连通性和内网穿透配置。只要接口地址、模型名和密钥正确,并选择适合格式转换的普通对话模型,就可以把 Smart Mermaid 变成一个可在局域网使用、也可安全访问的图表生成服务。