# 核心概念

来源: https://platform.lyrouter.com/ai_gateway/docs/concepts
更新日期: 2026-10-14

使用 LYRouter 先要分清三层关系：账号和工作空间决定资源归谁，API Key 决定谁在调用，模型和服务来源决定请求最终发往哪个上游。本页介绍贯穿整套文档的概念，以及一次请求在网关里经过的处理步骤。

## 账号、工作空间与 API Key

| 概念 | 说明 | 详见 |
| --- | --- | --- |
| 账号（Account） | 个人、团队或企业。订阅、Credits 余额和成员都属于账号；同一个用户可以同时属于多个账号，在控制台顶部切换 | [组织、成员与角色](https://platform.lyrouter.com/ai_gateway/docs/organization) |
| 成员角色 | 账号层只有账号管理员和成员两种。账号管理员管理成员、订阅和全部工作空间；成员只能进入被授权的工作空间 | [组织、成员与角色](https://platform.lyrouter.com/ai_gateway/docs/organization) |
| 工作空间 | 账号下隔离应用环境的单位。模型开通、API Key、BYOK、路由设置和请求日志都按工作空间划分。工作空间内的角色有查看者、编辑者和管理员 | [创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys) |
| API Key | 应用调用网关的凭证，属于一个工作空间。明文只在创建时显示一次；可以设置到期时间、预算和 IP 白名单 | [创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys) |

客户端里填写的永远是 LYRouter API Key。你在服务商处申请的 API Key 用于 BYOK，在控制台配置，不要填到客户端里。

## 模型与服务来源

| 概念 | 说明 | 详见 |
| --- | --- | --- |
| 模型 ID | 请求中 `model` 字段的值，形如 `deepseek/deepseek-v4-flash`。从工作空间的 **模型广场** 复制，或调用 `GET /v1/models` 查询；不要填模型的展示名称 | [如何选择模型](https://platform.lyrouter.com/ai_gateway/docs/choose) |
| 服务来源 | 一个模型可以由平台来源（平台的服务商账号，按 Credits 计费）或 BYOK 来源（你自己的服务商账号）提供，两者可以同时存在 | [平台模型与 BYOK 如何选择](https://platform.lyrouter.com/ai_gateway/docs/byok-choice) |
| 服务商与通道 | 服务商是模型厂商的身份；通道是该服务商的一个具体接入点，包括地址、协议和接入方式。同一服务商的按量 API 和 Coding Plan 是两个通道 | [通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing) |
| 凭证 | 通道下实际用来调用上游的 API Key。同一通道内，你的 BYOK 凭证排在平台凭证前面 | [BYOK 费用与凭证管理](https://platform.lyrouter.com/ai_gateway/docs/byok-cost) |
| 虚拟模型 | 把主模型、备用模型、参数和系统提示词打包成一个名称，用 `@vmodel/<名称>` 调用 | [虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets) |
| Auto 智能路由 | 用 `lyrouter/auto` 调用，网关按任务难度在已开通的模型中挑选 | [Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto) |
| 默认模型 | 工作空间的一项路由设置：请求没写 `model`，或请求的模型全部失败时，由它接手 | [通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing) |

## 费用与治理

| 概念 | 说明 | 详见 |
| --- | --- | --- |
| Credits | 平台的计费单位。平台模型按用量扣除 Credits，BYOK 调用按次收取服务费。余额分为充值余额和赠送余额 | [计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing) |
| 订阅版本 | 个人版免费；团队版和企业版按席位订阅，到期且过了宽限期后调用会被拒绝 | [计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing) |
| 预算与配额 | API Key 可以设置 Token 或费用预算；安全围栏可以给成员、部门或工作空间设置配额。触顶后调用返回 429 | [预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota) |
| 安全围栏 | 按成员、部门、API Key 或工作空间生效的策略，包括模型访问控制、客户端访问控制和内容安全检测 | [安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails) |
| 请求日志 | 每次调用一条记录，详情顶部的 Request ID 是排查和提交问题时引用的编号 | [通过日志定位调用问题](https://platform.lyrouter.com/ai_gateway/docs/logs) |

## 一次请求的处理过程

一次调用在网关中大致经过以下步骤，任何一步被拒绝都会直接返回错误：

1. **识别身份**：网关根据 API Key 找到它所属的工作空间和账号。Key 无效返回 401；Key 已过期、来源 IP 不在白名单，或账号订阅已到期，会在这一步被拒绝。
2. **安全与额度检查**：执行该工作空间生效的安全围栏策略（客户端访问控制、内容安全检测）和配额。命中阻断策略返回 403，配额用完返回 429。
3. **确定模型**：`@vmodel/<名称>` 展开为虚拟模型的模型列表，`lyrouter/auto` 按任务难度挑选模型，没写 `model` 时使用默认模型。
4. **选择通道与凭证**：按工作空间的多渠道选路策略和 BYOK 偏好给通道排序，依次尝试。每次尝试前检查 Credits 余额（不足返回 402），并按实际选中的模型检查安全围栏的模型访问控制（禁止时返回 403）；当前通道失败时自动换下一个。
5. **调用上游并返回结果**：把请求转换成上游需要的协议后发出，再把结果按你调用的协议返回，支持流式输出。
6. **计费与记录**：按实际调用的模型和用量扣除 Credits，并写入请求日志。日志通常在调用结束后几秒内可以查到。

各步骤的报错原文和处理方法见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)；失败时如何换通道见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。