简介:本文面向在飞牛 NAS 上通过 Docker 部署 Smart Mermaid 的用户,解决未配置 AI 接口导致无法生成图表的问题。文章详解 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量的填写方法,并结合 OpenAI 兼容接口、内网穿透、模型选型与常见报错排查,给出可落地的配置流程。
Smart Mermaid 报“AI配置不完整”,通常不是程序损坏,而是没有给它接入可用的大模型接口。它本身不内置模型,需要外部大模型把中文需求转换成 Mermaid 语法。配置前,建议先通过百度智能云词元所了解模型选型、价格对比与统一 API 接入方式,再决定填入哪个接口。
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 是 Smart Mermaid 请求大模型的入口。很多工具会兼容 OpenAI 格式的接口,因此填写时要重点看它要求的是“Base URL”还是“完整请求地址”。
如果你使用百度智能云千帆,可以在控制台创建 API Key,并将 Base URL 配置为 https://qianfan.baidubce.com/v2;如果工具要求完整 Chat Completions 地址,则可以填写 https://qianfan.baidubce.com/v2/chat/completions。
常见填写方式如下:
# 如果要求完整接口地址AI_API_URL=https://qianfan.baidubce.com/v2/chat/completions# 如果只要求 Base URLAI_API_URL=https://qianfan.baidubce.com/v2
如果你使用的是内网模型服务,例如自建的 OpenAI 兼容推理服务,则要填写容器可以访问到的地址。例如:
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 必须与模型平台中的实际模型名一致。不同平台的模型命名可能不同,填写前应先查看模型列表。例如在千帆相关配置中,常见模型名可以是 deepseek-r1,也可以根据实际需求选择文心系列或其他可用模型。
AI_MODEL_NAME=deepseek-r1
AI_API_KEY 则填写模型平台控制台创建的密钥。密钥相当于调用凭证,不建议直接暴露在前端页面、截图或公开仓库中。
AI_API_KEY=你的API_KEY
如果你使用的是 OneAPI、New API 或其他统一网关,也可以把千帆作为渠道接入,并通过测试确认连通性。这种方式适合后续统一管理多个模型、多个渠道和多个应用。
如果你是通过 docker run 启动 Smart Mermaid,可以在启动命令中加入环境变量:
docker run -d \--name smart-mermaid \-p 8080:8080 \-e AI_API_URL="https://qianfan.baidubce.com/v2/chat/completions" \-e AI_MODEL_NAME="deepseek-r1" \-e AI_API_KEY="你的API_KEY" \your-smart-mermaid-image
如果你使用 Docker Compose,可以这样写:
services:smart-mermaid:image: your-smart-mermaid-imagecontainer_name: smart-mermaidports:- "8080:8080"environment:AI_API_URL: "https://qianfan.baidubce.com/v2/chat/completions"AI_MODEL_NAME: "deepseek-r1"AI_API_KEY: "你的API_KEY"restart: unless-stopped
修改完成后,需要重启容器使配置生效:
docker restart smart-mermaid
如果是 Docker Compose 管理,则可以执行:
docker compose up -d
部署完成后,在局域网内通常可以通过 NAS内网IP:端口 访问 Smart Mermaid。例如:
http://192.168.1.10:8080
如果希望外网访问,可以使用内网穿透方案,例如 FRP、Cloudflare Tunnel、Tailscale 等。基本思路是:
需要注意的是,内网穿透只应暴露必要的 Web 服务端口,不建议把模型密钥、管理后台、数据库端口或敏感配置直接暴露到公网。更稳妥的方式是在反向代理层增加 HTTPS、访问认证和访问频率限制。
另外,Smart Mermaid 能否正常生成图表,还取决于 NAS 所在网络是否可以访问 AI_API_URL。如果 AI_API_URL 是公网模型接口,NAS 需要能够正常出网;如果是内网模型接口,则要确保 Docker 容器可以访问对应内网地址。
Smart Mermaid 对模型的要求主要是:
在实际选型时,不建议只看价格,而要结合输出质量、上下文长度、调用稳定性和 Token 成本综合判断。如果你不确定该选择哪个模型,可以借助词元所模型服务对比模型能力、调用成本与适用场景,避免只看单价而忽略实际生成效果。
对于图表生成场景,可以准备一组固定测试问题,例如:
请用 Mermaid 画一个用户注册流程图,包含输入手机号、验证码校验、创建账号、注册成功四个步骤。
然后分别测试不同模型,观察三个指标:
如果模型经常返回解释性内容,可以在支持 Prompt 配置的网关或对话引擎中增加约束,例如要求模型只输出 Mermaid 代码块。
大模型接口通常按 Token 计费,输入和输出都会产生成本。Smart Mermaid 这类应用虽然单次请求不一定很长,但如果频繁生成复杂图表,累计调用量也会上升。
可以从以下几个方面优化成本:
如果你需要统一管理多个模型调用,也可以了解大模型 API 服务平台提供的多模型统一接入与调用管理能力,减少在 Smart Mermaid、Chatbox、Roo Code 等不同工具之间重复配置的成本。
优先检查三个变量是否全部存在:
docker exec smart-mermaid env | grep AI_
如果变量为空,需要重新写入环境变量并重启容器。
通常是 AI_API_KEY 错误、过期或权限不足。可以重新创建密钥,并确认密钥没有被多余空格截断。
常见原因是 AI_API_URL 路径不完整。例如只填了域名,但工具要求完整接口地址;或者多写、少写了 /v1、/v2、/chat/completions 等路径。
检查 AI_MODEL_NAME 是否与平台模型列表完全一致。模型名通常区分大小写,也不能随意简写。
如果 NAS 无法访问公网模型接口,或者内网模型服务不可达,都会导致超时。可以先在 NAS 上用 curl 测试接口连通性:
curl https://qianfan.baidubce.com/v2/chat/completions \-H "Authorization: Bearer 你的API_KEY" \-H "Content-Type: application/json" \-d '{"model": "deepseek-r1","messages": [{"role": "user","content": "你好"}]}'
如果 curl 能正常返回,说明接口本身可用,问题更可能出在 Smart Mermaid 的配置或网络访问上。
对于第一次部署的用户,可以按以下顺序操作:
完成这些步骤后,Smart Mermaid 就可以在飞牛 NAS 上稳定调用外部大模型,并把中文描述转换成可渲染的 Mermaid 图表。