> ## 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 的系统，可以优先采用兼容接入方式，逐步迁移到底层多供应商能力。

```python theme={null}
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**，减少多模型接入的工程复杂度

* **模型元数据丰富**，可按用途、模态、能力、价格、上下文窗口和可用性筛选

* **官方通道与私有通道并存**，既能快速使用平台能力，也能接入企业自有资源

* **连通性测试与批量测试前置**，降低发布后调用失败风险

* 与**费用中心联动**，形成调用前检查、调用后结算、账单追踪的完整闭环