1. Zentrix 概览与配置流程

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向首次接触 Zentrix 的管理员，说明产品解决什么问题、平台由哪几部分组成、谁在哪个入口做什么，并用一条完整路线带着完成首次配置：接入上游、确认模型并创建模型分组、分发给成员、成员获取 API 密钥、发起调用、查看调用记录。读完本章，管理员可以让第一位成员成功调用模型，并在控制台里查到这次调用。后续各章都在本章建立的对象上继续配置。

1.1 产品定位

Zentrix 是部署在企业内部的模型与工具统一接入网关。业务系统、开发工具和外部智能体不再各自对接每一家模型厂商，而是统一通过 Zentrix 调用。网关在中间承担四件事：

平台在逻辑上分为控制面与网关数据面：

• 控制面提供管理后台与工作台，保存组织、模型、规则等配置，并把这些配置下发到网关节点。
• 网关数据面接收业务调用，在网关上完成认证、按规则处理，再转发给上游。调用记录由数据面产生，回传到控制台。

在「管理后台 › 运行总览」中可以看到全公司的运行指标：总消耗费用、总 Token、网关耗时 P95、网关实时并发，以及模型调用交付成功率及其失败构成（平台配置拒绝、上游故障、调用方取消、传输中断、未归类）。这些数字来自真实的网关调用，不是估算值。

组件自身的运行状态在 /platform-status 平台状态页查看。页面按组件列出探活时间线，社区版部署默认包含 PostgreSQL、SpiceDB、容器运行时、IDP、模型网关、ClickHouse、对象存储七项。时间线用于判断某个依赖是否在观察窗口内出现过中断，与业务指标相互独立。

注意：交付成功率的分母包含被平台规则拒绝的请求。做容量评估时，先看失败构成，再判断是上游不稳定还是策略配置不符合预期。

1.2 角色与入口

两个使用面

成员侧与管理员侧看的是同一批对象，只是姿态不同：成员在「模型广场」看到的是已发布、且自己在可用范围内的模型，在「设置 › API keys」看到的是自己的密钥；管理员在「模型」「模型分组」「API 密钥管理」看到的是全部模型、全部分组与全部密钥。

管理角色

管理权限以「对象 × 动作」为单位（例如「流量规则 · 新建」），一组权限组成一个角色，角色经「授予」赋给成员或职能组，范围为全租户或某个部门（含下级部门）。平台内置 8 个角色，也可以新建自定义角色：

系统管理员、安全管理员、审计员两两互斥，同一成员只能持有其中一类权限，用于满足三员分立要求；运营、财务、只读审计可以与其他角色叠加。各角色的完整权限、自定义角色、授予与按部门委派见 3.5。

菜单可见性

看不到某个菜单时，按以下顺序核对三件事：

1. 管理范围：租户管理后台与平台管理后台是两级。租户管理员只能看到本租户的菜单；租户管理后台的地址栏直接输入平台页面（例如 /admin/tenants）会被送回「运行总览」，相应的平台接口返回 403。两级边界见 2.6。
2. 授予：侧栏只出现成员经授予有权查看的入口，页面中的按钮只出现被允许的操作。例如系统管理员的侧栏不含 SSO 配置、成员与部门、角色管理与操作审计；按部门授予的成员只看到其角色涉及的入口，且只看到范围内的记录。
3. 许可模块：许可证未包含某个加购模块时，对应菜单不显示，相关接口拒绝访问（见 2.7）。

1.3 首次配置路线

首次配置的目标是：让一位成员用自己的 API 密钥成功调用一个模型，并且管理员能在控制台查到这次调用。

开始前确认：已用管理员账号登录管理后台；已准备好上游模型厂商的地址与账号密钥，或本地推理服务的地址。

步骤 1：接入上游模型来源

在「管理后台 › 模型 › 模型供应商」中添加上游。供应商对象保存请求地址、请求格式与账号密钥，是平台连接一个上游来源的唯一方式。厂商内置目录覆盖主流公有云、聚合平台与本地部署的推理服务；接入本地服务时按部署类型选择对应的请求格式。

你会看到：保存前，每个要启用的上游模型在「将成为模型」一栏给出去向：同名的关联到已有模型，其余默认新建同名模型，可以改名。保存后供应商出现在列表中，「管理后台 › 模型 › 模型」中出现对应的模型；只有启用的上游才会为模型提供服务。

字段含义、连接测试与定价见第 4 章、第 5 章。接入方式以当前界面为准。

步骤 2：确认模型并创建模型分组

平台中有三个对象：上游是供应商侧的具体模型；模型是调用方请求时使用的调用名，由一个或多个上游提供；模型分组是一组模型的集合，授权与配额都挂在分组上，成员不需要知道背后的供应商是谁。三个对象的完整说明见第 6 章。

1. 进入「管理后台 › 模型 › 模型」，确认步骤 1 启用的上游已出现为模型，「上游」列列出对应的供应商。
2. 打开模型详情，在「试用」页签发送一条消息，确认模型能正常返回回复。
3. 进入「管理后台 › 组织与权限 › 模型分组」，点「添加模型分组」。
4. 填写名称与描述。名称按用途取，例如「通用对话」「低价批处理」；描述里建议写明适用任务与成本等级，成员在模型广场会看到这段文字。
5. 点「添加模型」，勾选要纳入分组的模型，保存。

你会看到：试用时先显示进度条，随后返回完整回复，回复下方显示首字耗时、总耗时与 Token 数。分组保存后出现在「模型分组」列表中，详情页有「基本信息」「可用范围与配额」「调用情况」「操作审计」等页签。

注意

• 同一个模型可以出现在多个分组中；按用途拆成多个分组，便于分别设置可用范围、配额与计价。
• 试用会真实计费，也计入调用记录与操作审计。
• 推理型模型的输出长度由 max_tokens 约束。把 max_tokens 设得过小时，推理过程会先耗尽额度，正文返回为空、结束原因为长度截断，这属于上游的正常表现，不是网关故障。试用时不要设置过小的上限。

步骤 3：分发给成员（设置可用范围）

新建的模型分组默认没有可用范围，任何人都不能使用。

前提：目标成员、部门或职能组已存在于「组织与权限 › 成员与部门」（见第 3 章）。

操作步骤

1. 打开分组详情，切到「可用范围与配额」页签，点「编辑可用范围」。
2. 在弹窗左侧下拉中切换授权对象类型：所有用户、部门、职能组、工作空间，或按成员逐一勾选。勾选后右侧列出已选对象。
3. 点「下一步」，进入「配置目标有效期」。保留「长期有效」，或选择固定的天数与自定义起止时间。
4. 点「保存」。

你会看到：保存后可用范围表按对象逐行列出，包含范围名称与类型。

注意

• 授权后，范围内的成员才能在模型广场看到分组内的模型，并在「获取 API 密钥」的归属下拉中选到该分组；范围外的成员看不到这些模型，直接访问管理端详情地址会被整页重定向回自己的设置页。
• 把成员移出可用范围后，成员侧不再看到该分组，其原有密钥经该分组的调用随后转为被拒绝（返回 401 invalid_api_key）。授权变更下发到网关需要一定时间，不是瞬时完成；撤权后如需确认已生效，按 3.9 的方式核对。
• 配额与预算在同一页签设置，见第 7 章。

步骤 4：成员获取 API 密钥

API 密钥由成员本人在工作台创建，每把密钥绑定一个模型分组，可以调用该分组内的全部模型。

1. 成员登录工作台，点顶部「模型」进入模型广场，用搜索框、厂商或分类找到要用的模型，打开详情。
2. 点「获取 API 密钥」。
3. 在「API 密钥归属」中选择归属于哪个授权对象。下拉只列出本人在可用范围内的分组，形如「个人专属 · 通用对话」或「研发中心 · 部门 · 通用对话」。「指定 API 密钥（可选）」留空时由系统生成。
4. 选择挂靠的客户端，或新建一个客户端。客户端用于在用量与请求记录中区分调用来源。
5. 点「创建」。

你会看到：密钥出现在列表中，状态为「正常」，创建后即可调用。成员在「设置 › API keys」中能看到这把密钥及其最近使用时间；管理员在「管理后台 › 组织与权限 › 模型分组 › API 密钥管理」中能看到同一把密钥的归属、调用方、计费对象与状态。

注意：密钥在列表中按掩码显示，请复制后妥善保存。不要在多个人或多个系统之间共用同一把密钥；需要区分调用来源时，分别创建密钥并挂到不同客户端。

步骤 5：发起调用

模型详情的「首次调用 API」页签给出本平台的接入地址与各协议的示例代码，可直接复制。以 OpenAI 兼容协议为例：

curl https://<网关地址>/api/v1/agent-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [{"role": "user", "content": "用一句话介绍你自己。"}]
  }'

使用 OpenAI SDK 时只需改两处：base_url 设为 https://<网关地址>/api/v1/agent-gateway/openai/v1，api_key 设为本人的 API 密钥。对话补全与 Responses 两类接口都兼容，SDK 的其他调用方式不变。

你会看到

• 对话补全返回标准的 chat.completion 结构，包含 choices、message 与 usage；推理型模型还会额外返回 reasoning_content。Responses 接口返回标准的 response 对象，output 中同时包含 message 与 reasoning 两段。
• 成功的响应头带链路 ID（x-trace-id），用于在控制台定位这次调用。
• 返回 HTTP 200 即表示调用已经过网关、被派发到上游并成功返回。

注意

• 接入地址以模型详情「首次调用 API」页签显示的为准；根路径 /v1/... 不是网关入口。
• 旧版补全接口（completions）对本平台多数模型不适用。请求在网关侧即被拒绝，返回 400 MODEL_ENDPOINT_UNSUPPORTED，不会派发到上游，也不计费。请改用对话补全或 Responses 接口。
• 查询模型列表（models.list()）返回的是本密钥所在环境的模型集合，可能包含当前密钥不能调用的模型。可用范围以「API 密钥归属」所选分组为准；调用范围外的模型返回 404 model_not_found。
• 密钥无效或已失效时返回 401 invalid_api_key。错误码与处理建议见附录。

步骤 6：查看调用记录

管理员查看

1. 进入「管理后台 › 运行总览」，切到「请求」页签。
2. 用搜索框或筛选条件收敛列表：可按模型名、发起人、结果、时间范围筛选。
3. 点击记录打开详情，在「概要」「请求」「路由与改写」三个页签中核对发起人与凭据、请求与响应体积、耗时分解，以及本次命中的流量规则。

你会看到

• 成功的调用显示为「已完成」，并给出端到端耗时与上游耗时。
• 被网关拒绝的请求同样会记录一行，结果为「失败」并标注 HTTP 状态码；在网关侧就被拒绝的请求耗时为 0，计费为 0，其「路由与改写」中会说明本次没有上游尝试。
• 「所属空间」显示调用者自己的工作区，便于按人核对。

成员查看：成员在工作台中按时间逐条查看本人的调用，包括所调用的模型、状态、Token、耗时与费用。

注意：按链路 ID 检索若未命中，改用模型名加时间范围收敛列表，再按时间戳定位。

1.4 后续配置顺序

首次调用打通后，建议按以下顺序完善配置，再逐步扩大使用范围：

1. 组织与身份：建立部门、职能组与成员，接入 SSO 与通讯录同步，指定系统管理员、安全管理员、审计员，设置会话与密码策略（第 3 章）。
2. 模型完善：补充上游账号与定价，按用途拆分模型分组，设置配额与预算（第 4 章至第 7 章）。
3. 能力接入：按需接入 MCP 服务与 API 服务，设置可用范围（第 11 章、第 12 章）。
4. 流量与安全：在「流量 › 流量规则」中配置路由、限额、内容检测与工具级权限，保存前用规则预览核对命中顺序（第 15 章）。
5. 告警与审计：配置通知渠道与告警规则，确认日志留存与操作审计符合合规要求（第 22 章）。
6. 分阶段上线：先在试点部门完成正常调用、拒绝、额度耗尽与异常输入的验证，再推广（第 25 章、第 26 章）。

1.5 配置完成标准

• 成员能在模型广场看到获授权分组内的模型，用本人密钥调用成功；可用范围以外的账号看不到这些模型，调用被拒绝。
• 模型的「试用」返回完整回复，并显示首字耗时、总耗时与 Token。
• 管理员能在「运行总览 › 请求」中找到试点调用，发起人、凭据与用量正确；成员能看到同一次调用。
• 把成员移出可用范围后，成员侧的分组消失，旧密钥的调用转为被拒绝，且能在「运行总览 › 请求」中查到这些被拒绝的请求。
• 系统管理员、安全管理员、审计员由不同人员担任，配置变更能在操作审计中查到操作人与时间。
• 告警接收人、备份恢复责任人与技术支持联系人已经明确。

能力说明

---

下一章：2. 平台对象和边界