3.3 智能体与 AI 网关

一句话判断

智能体是“开箱即用的 AI 应用”（带 WebUI、带频道、带技能），AI 网关是“统一管模型调用的中控”（管配额、管路由、管审计）。前者让你快速用上 AI，后者让你管住 AI——前者社区版就能玩，后者是企业版的能力。

智能体：不只是“装个聊天应用”

智能体集中在 AI → 智能体 页面安装和管理。页面包含智能体列表、模型账号，以及按智能体类型和版本动态显示的配置能力。

版本边界：社区版最多管理 5 个智能体，专业版和企业版不限数量。企业版用户需要对应的智能体查看或管理权限。

很多人把智能体理解为“装个 ChatGPT-Next-Web”，只对了一半。1Panel 的智能体管理包含五个维度的配置：概览、模型、频道、技能与角色、设置。区别在于：1Panel 把“应用 + 模型账号 + 运维”串成了一条链。

使用前提

官方列了四条：

1. Docker 服务和应用商店状态正常；
2. 已准备模型服务及 API Key（或先在模型账号里建好）；
3. 服务器能访问智能体应用镜像和软件源；
4. 对外开放 WebUI 或频道前，已完成防火墙、域名、HTTPS 和访问控制配置。

第 4 条是“对外开放”的分水岭：第 1~3 条让你装得上，第 4 条决定你敢不敢给别人用。

安装智能体：五步

1. 进入 AI → 智能体；
2. 点击 创建，选择页面当前支持的智能体类型；
3. 填写名称、应用版本、WebUI 端口、认证信息和允许访问地址；
4. 选择或新建模型账号，并按需配置模型池和备用模型；
5. 确认参数后提交任务，在任务日志中查看安装结果。

“允许访问地址”是安装时最重要的一个安全字段。 官方明确：

允许访问地址需要使用 http:// 或 https:// 开头的域名或 IP；只填写可信来源，避免把智能体管理界面直接暴露到公网。

为什么这条值得单拎出来说：智能体的 WebUI 往往带管理功能（配 API Key、看对话记录），暴露到公网 + 弱密码，就是一次数据泄露。内网自己用，就填内网地址；要公网用，先配好域名和 HTTPS。

“备用模型”是进阶选项：主模型挂了（或者厂商限流了），智能体自动切到备用。3.1 节说的“云端为主、本地兜底”就是靠这个实现的。

日常管理：五个标签

频道是智能体超越“聊天应用”的地方：配置好后，同一个智能体能被企业微信、钉钉、飞书的群使用——你的群机器人背后是 1Panel 管理的模型和技能。

“修改频道配置可能自动重启容器”这条要记住：配置频道时挑业务低谷，避免正在使用的会话被中断。

技能与角色：技能让智能体能做额外的事（查天气、搜知识库），角色（Role）是预先设定的人设。角色是 Markdown 文件，可以直接编辑——这是进阶玩家定制智能体行为的主要入口。保存后按页面提示重启容器生效。

设置的配置文件编辑：官方建议“直接编辑配置文件前建议先备份；保存后需要重启的配置以页面提示为准”。这和 1.2 节改 OpenResty 配置是同一个心法：先备份，再动手。

多节点与批量操作（企业版）

企业版可以对不同节点上的智能体执行批量任务，并向目标智能体下发 Skill。

官方提醒：提交前应核对目标节点、目标版本和 Skill 来源，任务结果可在任务日志中查看。 批量操作的放大效应是双向的——批量升级方便，批量翻车也同样壮观。先在单节点试，再批量推。

AI 网关：企业版的模型中控

AI 网关用于统一管理模型账号、调用凭证、访问配额和请求转发。客户端只需配置网关的外部连接地址和 API Key，就能通过统一入口调用不同供应商或本地部署的模型。

这是企业版功能。 新版 AI 网关有 8 个功能入口：账号池、模型组、API Key、用户组、智能路由、内容合规、用量统计、设置。

首次配置顺序（官方推荐）

1. 在账号池导入模型账号并配置模型映射；
2. 按需创建模型组，用于限制用户组可用模型或配置智能路由；
3. 创建用户组，设置 QPS、Token 配额和模型范围；
4. 创建 API Key，交给客户端使用；
5. 按需启用智能路由、内容合规、用量统计和 Elasticsearch。

这个顺序是设计出来的，别跳步：没有账号池就没有可用模型，没有用户组就没有配额载体，API Key 绑定用户组才有意义。

核心概念对照

模型映射是网关的核心价值之一：客户端代码里写死 model: gpt-4o，你在网关把它映射到任何模型——换模型不动代码。

负载策略有两种：

API Key 管理的两个坑

第一，API Key 只在创建时完整展示。 官方原话：保存好，重置 Token 后原 Token 立即失效，需要同步更新客户端配置。和移动端那条一个道理——敏感凭据只露一次面。

第二，默认用户组不可删除。 API Key 绑定用户组后继承其 QPS、Token 配额和模型范围。

客户端调用方式（官方示例）：

curl http://<服务器 IP>:4000/v1/chat/completions \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Base URL 用页面顶部的外部连接地址，model 填账号池里的请求模型名；启用智能路由后也可以填 auto。

智能路由：auto 的魔法

智能路由根据请求复杂度，在简单模型组和复杂模型组之间选择模型。只在客户端请求使用 model=auto 时触发；请求其他模型名时按普通转发。

配置流程：

1. 在模型组中分别创建简单模型组和复杂模型组；
2. 在 设置 → Embedding 配置 Embedding 服务、路由阈值和 TopK；
3. 在 设置 → 智能路由 中启用，选择两个模型组；
4. 在 智能路由 → 样本 中维护简单/复杂请求样本，生成或重建向量；
5. 客户端用 model=auto 发请求。

Embedding 服务是智能路由和内容合规的共同依赖。 官方给了一条完整的本地部署路径：用模型下载器下载 Qwen3-Embedding-0.6B-GGUF 到 /opt/1panel/ai/models，应用商店装 llama.cpp，模型目录设 /opt/1panel/ai/models（容器内挂载为 /models），启动参数：

-m /models/Qwen3-Embedding-0.6B-GGUF/qwen3-embedding-0.6b-q8_0.gguf \
  --host 0.0.0.0 --port 8080 --embedding --pooling last -c 32768

然后在网关 设置 → Embedding 填 http://127.0.0.1:8080、模型 Qwen3-Embedding-0.6B、API Key 留空（本地 llama.cpp 未配认证时）。点连接测试，成功后保存，再回样本页面重建向量。

“预览”功能很好用：输入一段文本看它被判为简单还是复杂，只走路由判断不真实调用上游——调参时不花 Token。

一个决策参数：路由阈值——请求与样本的相似度达到该值才采用样本匹配结果。阈值太高 → 大量请求走规则判断；阈值太低 → 容易误判。 结合决策日志（记录判定标签、来源、置信度）一起调。

内容合规与用量统计

内容合规支持敏感词匹配（含分组、归一化词、阻断/仅记录两种动作）和基于 Embedding 的语义审核样本。用量统计提供分布、排行榜、调用日志三个视图，支持按用户、模型供应商、模型和关键字筛选。

用量统计是企业里最实用的页面：哪个部门用了多少 Token、哪个模型最贵、缓存命中率多少，全都有。Token 成本失控的企业，十有八九是没用过这个页面。

网关设置还有性能设置（最大并发、等待队列、超时、最大请求体）和 Elasticsearch 设置（保存请求和响应内容以便审计）。Elasticsearch 里可能包含提示词和用户输入，官方提醒按合规要求限制访问范围、账号权限和数据保留周期。

智能体 vs AI 网关：一张决策表

本节要点

• 智能体社区版最多 5 个，专业版/企业版不限；
• 安装时的允许访问地址只填可信来源，别把管理界面裸曝公网；
• 改频道配置可能自动重启容器，挑低谷操作；
• 角色是 Markdown 文件，保存后按提示重启容器；
• AI 网关是企业版功能，按“账号池 → 模型组 → 用户组 → API Key”的顺序配置；
• API Key 只在创建时完整展示；智能路由只对 model=auto 生效；
• 智能路由和内容合规都依赖 Embedding 服务，改了 Embedding 要重建向量。

智能体的完整管理说明见 《1Panel 官方文档：功能手册》 的“智能体”与“AI 网关”章节。

下一节：让 AI 长出“手”——MCP 让智能体调用外部工具，Skills Hub 让企业统一管理这些技能，见 3.4 节。