Documentation Index
Fetch the complete documentation index at: https://docs.zgi.cn/llms.txt
Use this file to discover all available pages before exploring further.
ZGI 中的智能体、工作流、知识库和开发者 API 都依赖模型能力。模型网关把不同模型供应商、官方通道、企业私有通道、自定义模型、API Key、默认模型、调用计费和连通性测试统一到同一套治理体系中，让团队可以用一致的方式接入、选择和管理模型。
一句话理解
模型网关是适用于多模型的一体化调用入口：对外提供 OpenAI 兼容体验，对内完成供应商适配、通道路由、模型可用性治理、额度扣减和调用追踪。
模型网关是什么
| 核心对象 | 说明 |
|---|
| Provider（供应商） | 管理 OpenAI、Anthropic、Google、国内模型服务商以及企业自定义供应商 |
| Model（模型） | 统一记录模型名称、能力类型、上下文窗口、输入/输出价格、能力标签、可用性和启用状态 |
| Channel（通道） | 承载真实调用凭证、Base URL、模型列表、优先级、权重、余额和连通性状态 |
| API Key | 面向开发者或业务系统的调用凭证，可配置额度、过期时间、模型范围和 IP 白名单 |
| Default Model（默认模型） | 按对话、向量、重排、视觉、生图等用途设置默认模型，降低应用配置成本 |
| Billing（计费） | 调用前进行额度预扣，调用完成后按实际 Token、模型价格和通道信息结算 |
模型网关关键构成
| 模块 | 能力说明 |
|---|
| 供应商管理 | 查看供应商列表和详情，启用/停用供应商，创建、更新、删除企业自定义供应商 |
| 模型管理 | 按供应商、用途、能力、输入/输出模态、状态搜索模型，启用/停用单个或批量模型 |
| 自定义模型 | 录入私有模型或兼容模型的名称、用途、上下文窗口、价格、端点和参数能力 |
| 默认模型 | 为对话、向量、重排、视觉、生图等场景配置默认模型，系统也支持自动解析可用模型 |
| 通道管理 | 创建组织私有通道，配置 API Key、Base URL、模型映射、优先级、权重和标签 |
| 官方通道 | 查看平台官方通道及可用模型，调整官方通道组的优先级、权重和启用状态 |
| 连通性测试 | 支持通道测试、指定模型测试、草稿测试和多模型批量测试，返回成功状态与响应耗时 |
| 调用凭证 | 创建和管理 LLM API Key，支持配额、模型限制、IP 白名单、过期时间和状态控制 |
支持的模型类型与用途
| 类型 / 用途 | 说明 |
|---|
| 大语言模型 / 文本对话 | 用于智能体对话、工作流 LLM 节点、文本生成和结构化理解 |
| Embedding / 向量模型 | 用于知识库向量化、语义搜索和相似度召回 |
| Rerank / 重排模型 | 用于知识库检索结果重排，提高复杂问题的命中质量 |
| 视觉模型 | 用于图片理解、图文问答和文档图像分析 |
| 图像生成模型 | 用于提示词生图和工作流图像生成节点 |
| 语音转文本 / 文本转语音 | 用于语音输入、语音播报和多模态交互 |
| 实时语音、视频生成、审核 | 用于实时音频、视频生成和内容安全等扩展场景 |
路由与降级
ZGI 通过通道的优先级和权重实现模型调用路由。优先级用于决定通道选择顺序，权重用于在同优先级通道之间分配流量。企业可以同时配置官方通道与私有通道，在成本、稳定性、地域合规和供应商冗余之间做平衡。
-
通道启用 / 停用 — 快速将异常通道从路由中移除
-
模型映射 — 把平台模型名映射到供应商真实模型名，兼容不同服务商命名差异
-
参数与 Header 覆盖 — 对特定通道附加请求参数或请求头
-
连通性测试 — 上线前验证单模型或多模型可调用性，减少运行时失败
-
官方通道监听 — 后端支持通道事件流，网关实例可接收通道创建、更新、启用、禁用等变更
如何接入模型
查看已有模型
进入「模型管理」查看已有供应商和模型，确认所需模型是否已在平台元数据中。
使用官方通道
进入「通道」确认官方通道组是否启用，并查看平台可用模型。
接入企业自有账号
创建组织私有通道，填写供应商、API Key、Base URL 和模型列表。
执行连通性测试
执行通道测试或指定模型测试，确认 chat、embedding、image-gen、rerank 等方法可用。
启用与配置默认模型
在「模型管理」启用模型，必要时创建自定义模型；在「默认模型」中为对话、向量、重排、视觉、生图等用途设置默认模型。
创建调用凭证
为开发者或系统集成创建 API Key，并限制模型范围、额度、有效期和来源 IP。
OpenAI 兼容调用
模型网关的目标是降低开发者集成成本。开发者可以使用统一的模型名称、统一的鉴权方式和统一的调用语义接入不同供应商模型；平台侧负责供应商适配、模型映射、路由、计费和追踪。对于已有 OpenAI SDK 的系统，可以优先采用兼容接入方式，逐步迁移到底层多供应商能力。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_ZGI_API_KEY",
base_url="https://api.zgi.cn/v1" # 或本地: http://localhost:2678/v1
)
response = client.chat.completions.create(
model="zgi-default",
messages=[{"role": "user", "content": "总结这份合同的关键条款"}],
)
print(response.choices[0].message.content)
成本与追踪
-
模型元数据记录 input_price、output_price、cached_input_price、上下文窗口和最大输出 Token
-
调用结算记录模型、供应商、通道、请求 ID、响应耗时、Token 用量、成本和状态
-
API Key 维度可记录已用额度和剩余额度，便于按系统、应用或集成方追踪
-
私有通道支持余额调整，适合企业自带模型账号或按渠道结算的场景
典型场景
| 场景 | 配置建议 |
|---|
| 多供应商容灾 | 同一模型用途配置多个通道，当单一供应商不可用时快速切换 |
| 成本分层 | 日常任务使用高性价比模型，复杂推理或高价值场景使用旗舰模型 |
| 私有模型接入 | 把本地部署模型或企业专属模型纳入统一模型选择器 |
| 研发集成 | 通过 API Key 为内部系统提供统一模型调用入口，并按模型和额度控制风险 |
| 知识库增强 | 统一配置 Embedding 与 Rerank 模型，保证 RAG 的索引与召回质量 |
ZGI 模型网关的优势
-
统一供应商、模型、通道和 API Key，减少多模型接入的工程复杂度
-
模型元数据丰富，可按用途、模态、能力、价格、上下文窗口和可用性筛选
-
官方通道与私有通道并存，既能快速使用平台能力，也能接入企业自有资源
-
连通性测试与批量测试前置，降低发布后调用失败风险
-
与费用中心联动，形成调用前检查、调用后结算、账单追踪的完整闭环