AIRouter/0-req.md

# 边缘 AI 算力机统一 AI 通讯层 — 需求规格说明书

> 文档定位：基于《边缘 AI 算力机统一 AI 通讯层设计方案》提炼的需求规格，用于指导研发实施与验收。
>
> 版本：1.0 | 状态：初始草案

---

## 1. 概述

### 1.1 项目背景

边缘 AI 算力机同时运行大语言模型、视觉模型、语音模型、Embedding 模型和重排序模型。随着接入应用增多，各应用直接调用推理服务（Ollama、vLLM、llama.cpp、TensorRT-LLM、Triton 等）将导致：接入协议不统一、上下文缺乏管控、并发导致显存不足、缺少排队与优先级机制、连接断开后算力浪费、重试风暴、无法统一监控、缺少降级与云端路由、模型替换影响所有业务。

### 1.2 项目目标

在业务应用与底层推理服务之间建设 **统一 AI 通讯层（Edge AI Gateway）**，作为所有 AI 请求的唯一入口，对每次 AI 调用进行标准化接入、上下文控制、排队调度、连接管理、资源治理和运行监控。

### 1.3 目标用户

- **业务应用开发者**：通过统一 API 调用 AI 能力，不关心底层模型部署细节。
- **系统管理员**：配置模型、配额、安全策略和监控告警。
- **运维人员**：通过指标、日志和调用链进行故障排查和容量规划。

### 1.4 范围与边界

| 类别 | 包含 | 不包含 |
|---|---|---|
| 功能范围 | 统一 API 网关、认证配额、会话上下文、队列调度、模型路由、连接管理、资源治理、可观测性、安全审计 | 模型训练与微调、数据标注、知识库构建与管理 |
| 部署范围 | 单机部署为主，预留多节点扩展接口 | 第一阶段不实现完整分布式调度 |
| 模态范围 | 文本生成优先，预留多模态接口 | 第一阶段不实现视觉/语音推理适配 |

---

## 2. 目标与非目标

### 2.1 建设目标

1. **统一接入** — 向业务应用提供稳定、标准、版本化的 AI API。
2. **统一上下文** — 集中管理会话、历史消息、系统提示词、知识检索结果和 Token 预算。
3. **统一调度** — 根据优先级、租户配额、模型能力和设备资源进行排队与执行。
4. **统一连接控制** — 管理连接建立、排队等待、首 Token、推理、空闲和总调用时间。
5. **统一模型路由** — 屏蔽 Ollama、vLLM、TensorRT-LLM、Triton 和云端模型接口差异。
6. **统一资源治理** — 控制 GPU/NPU/CPU、显存、KV Cache、模型驻留和并发执行槽位。
7. **统一可靠性机制** — 提供限流、背压、取消、熔断、幂等、重试和降级能力。
8. **统一可观测性** — 记录调用链、排队时间、推理耗时、Token 用量、资源使用和错误原因。
9. **统一安全策略** — 实现应用认证、租户隔离、权限管理、审计、脱敏和数据留存控制。
10. **降低业务耦合** — 业务应用只描述任务需求，不直接依赖模型部署方式。

### 2.2 非目标

- 不替代推理引擎本身的功能（如模型加载、量化、批处理引擎实现）。
- 第一阶段不实现完整的多节点分布式调度和跨节点任务迁移。
- 第一阶段不实现视觉、语音等多模态推理适配。
- 不提供模型训练、微调或数据标注能力。
- 不提供知识库的构建与管理功能。

---

## 3. 用户故事

### US-1：业务应用调用 AI 模型

> 作为业务应用开发者，我希望通过统一的 OpenAI 兼容 API 调用不同推理引擎的模型，这样我不需要关心底层是 Ollama 还是 vLLM，也不需要在模型替换时修改代码。

### US-2：高优先级任务优先执行

> 作为安防应用开发者，我希望安防告警任务能够优先于文档分析任务执行，这样在设备资源紧张时告警不会被批处理任务阻塞。

### US-3：客户端断开后停止推理

> 作为业务应用开发者，我希望在用户关闭浏览器或网络断开后，通讯层能自动取消正在进行的推理任务，这样不会浪费 GPU 算力和显存。

### US-4：上下文自动裁剪

> 作为业务应用开发者，我希望通讯层自动管理会话上下文的 Token 预算，这样当历史消息过长时能自动裁剪或摘要，而不是超出模型窗口导致报错。

### US-5：敏感数据不出域

> 作为系统管理员，我希望敏感数据的 AI 请求强制在本地模型处理，不允许降级到云端，这样能满足数据合规要求。

### US-6：监控与排障

> 作为运维人员，我希望通过统一的指标、日志和调用链查看每次 AI 调用的排队时间、首 Token 延迟、推理耗时和错误原因，这样能快速定位性能瓶颈和故障。

### US-7：任务状态查询与取消

> 作为业务应用开发者，我希望能查询提交的 AI 任务状态，并在需要时主动取消排队中或执行中的任务，这样能灵活控制任务生命周期。

### US-8：模型降级与云端路由

> 作为系统管理员，我希望在本地算力不足时，通讯层能按策略自动降级到小模型、备用节点或云端模型，并在审计日志中记录降级原因，这样能在保证可用性的同时控制成本和安全。

---

## 4. 功能需求

### FR-1：协议适配与 API 网关

#### FR-1.1：统一 API 接口

**The system shall** 提供 OpenAI API 兼容格式的统一接口，包括但不限于：

| 接口 | 方法 | 说明 |
|---|---|---|
| `/v1/chat/completions` | POST | 文本生成（流式/非流式） |
| `/v1/responses` | POST | 响应式接口 |
| `/v1/embeddings` | POST | 向量嵌入 |
| `/v1/audio/transcriptions` | POST | 语音转文字 |
| `/v1/audio/speech` | POST | 文字转语音 |
| `/v1/images/analyze` | POST | 图像理解 |
| `/v1/tasks` | POST/GET/DELETE | 异步任务管理 |
| `/v1/sessions` | POST/GET/DELETE | 会话管理 |
| `/v1/models` | GET | 模型列表 |
| `/health` | GET | 健康检查 |
| `/ready` | GET | 就绪检查 |

#### FR-1.2：多协议支持

**The system shall** 支持以下传输协议，按场景选择：

- **SSE** — 文本生成流式输出，浏览器和服务端接入。
- **WebSocket** — 实时语音、双向多模态和持续上传场景。
- **gRPC Streaming** — 内部服务间高性能通信。
- **MQTT** — 设备消息、弱网络和异步边缘任务。
- **普通 HTTP** — Embedding、分类和短时非流式任务。

#### FR-1.3：请求标识与幂等

**The system shall** 为每个请求生成全局唯一 `request_id`，并支持客户端提交 `idempotency_key` 实现幂等控制。

- 在有效期内，相同租户、应用和幂等键只能创建一个任务。
- 重复请求返回原任务状态或结果，不触发重复推理。

#### FR-1.4：边缘调度参数

**The system shall** 在标准 OpenAI 请求格式基础上支持以下扩展参数：

- `session_id` — 会话标识，用于上下文关联。
- `priority` — 请求优先级（P0–P4）。
- `max_output_tokens` — 最大输出 Token 数。
- `context_policy` — 上下文组装策略（如 `summary_and_recent`）。
- `timeouts` — 分层超时配置（`queue_ms`、`first_token_ms`、`inference_ms`、`total_ms`）。
- `routing` — 路由控制（`local_only`、`allow_smaller_model`）。
- `metadata` — 应用名、用户 ID、trace_id 等元数据。

#### FR-1.5：响应元数据

**The system shall** 在响应中返回以下元数据：

- `request_id`、`task_id`、`session_id`、`status`
- `logical_model`（逻辑模型名）、`actual_model`（实际模型名）、`node_id`
- `usage`（input_tokens、output_tokens、total_tokens）
- `timing`（queue_ms、first_token_ms、inference_ms、total_ms）
- `finish_reason`、`degraded`（是否降级）

#### FR-1.6：统一错误码

**The system shall** 使用稳定的业务错误码，不暴露底层推理引擎原始错误信息：

| 错误码 | 含义 |
|---|---|
| `AUTH_FAILED` | 身份验证失败 |
| `PERMISSION_DENIED` | 无模型或数据访问权限 |
| `RATE_LIMITED` | 请求频率超过限制 |
| `QUOTA_EXCEEDED` | 调用量或 Token 配额不足 |
| `INVALID_REQUEST` | 参数或输入格式错误 |
| `CONTEXT_TOO_LARGE` | 上下文无法在策略内压缩 |
| `QUEUE_FULL` | 队列已满 |
| `QUEUE_TIMEOUT` | 排队等待超时 |
| `FIRST_TOKEN_TIMEOUT` | 首 Token 超时 |
| `INFERENCE_TIMEOUT` | 推理超时 |
| `REQUEST_CANCELLED` | 请求已取消 |
| `MODEL_UNAVAILABLE` | 模型没有可用实例 |
| `RESOURCE_EXHAUSTED` | 显存或执行资源不足 |
| `POLICY_BLOCKED` | 安全或数据策略禁止执行 |
| `INTERNAL_ERROR` | 通讯层内部错误 |

---

### FR-2：认证、配额与限流

#### FR-2.1：应用认证

**The system shall** 支持以下认证方式：

- API Key 认证。
- JWT 令牌认证。
- mTLS 互信证书认证。
- 签名请求认证。

#### FR-2.2：权限控制

**The system shall** 实现以下权限控制：

- 应用只能访问授权的逻辑模型、知识库和工具。
- 高风险模型或工具采用单独授权。
- 管理接口与业务调用接口分离。
- 用户身份可通过 JWT 或可信请求头传递。

#### FR-2.3：限流与配额

**The system shall** 支持多层级限流与配额控制：

- 应用级并发上限和队列上限。
- 用户级并发上限和每分钟请求上限。
- 设备级全局并发上限和队列上限。
- 应用可使用的优先级范围由后台策略控制，普通应用不能直接声明最高优先级。

---

### FR-3：会话与上下文管理

#### FR-3.1：上下文组装

**The system shall** 按固定优先级组装模型上下文：

1. 平台级安全规则
2. 应用级系统提示词
3. 当前用户身份、角色和权限
4. 会话长期摘要
5. 最近若干轮原始对话
6. 知识库检索结果
7. 工具调用结果
8. 当前用户请求
9. 输出格式和输出长度约束

每段上下文须携带来源、时间、可信度、权限级别和 Token 数等元数据。

#### FR-3.2：Token 预算

**The system shall** 为每次调用预先计算 Token 预算，按模型单独配置，不直接使用模型标称上限。

- 预算应覆盖：系统指令、会话摘要、最近对话、知识检索、当前请求与工具结果、模型输出预留。
- 保留 5%～10% 的安全空间以避免边界误差。

#### FR-3.3：上下文超限处理

**When** 上下文超出 Token 预算，**the system shall** 按以下顺序处理：

1. 删除重复或低相关度的知识片段。
2. 压缩过长的工具返回结果。
3. 删除最早且无关键状态的对话。
4. 将较早对话转换为结构化摘要。
5. 降低检索结果数量或单段长度。
6. 在策略允许时切换到更大上下文模型。
7. 仍无法满足时返回 `CONTEXT_TOO_LARGE` 错误。

**The system shall not** 静默截断系统指令、权限信息、当前问题或输出约束。

#### FR-3.4：会话管理

**The system shall** 提供会话创建、查询、删除接口，并支持以下策略：

- 最大生命周期和空闲过期时间。
- 最大消息数和最大累计 Token 数。
- 租户、应用和用户之间严格隔离。
- 敏感字段脱敏或禁止持久化。
- 用户主动清除会话和记忆。
- 摘要模型、摘要版本和摘要时间记录。

#### FR-3.5：会话与记忆分层

**The system shall** 区分三类信息：

- **原始会话历史** — 用于审计和重新生成，不一定每次进入模型。
- **短期上下文** — 最近若干轮对话，直接进入当前 Prompt。
- **长期记忆** — 经提取和确认的用户偏好、业务状态或任务结论，按需检索。

#### FR-3.7：Prompt 注入防护

**The system shall** 对来自知识库、网页、文件和工具的内容标记为"不可信数据"，与系统指令分区组织，并执行以下防护：

- 限制外部内容覆盖系统规则。
- 对工具调用参数执行结构化校验。
- 对高风险工具增加权限确认。
- 过滤密钥、内部提示词和其他租户数据。
- 记录最终进入模型的上下文版本和哈希值。

---

### FR-4：任务队列与调度

#### FR-4.1：三级处理模型

**The system shall** 对每个请求执行三级处理：

1. **接入准入** — 鉴权、配额、限流、输入和 Token 检查。
2. **排队调度** — 优先级、公平性、队列超时和模型选择。
3. **执行控制** — 模型并发、显存准入、批处理、取消和资源释放。

#### FR-4.2：优先级队列

**The system shall** 支持五级优先级：

| 等级 | 任务示例 | 调度目标 |
|---|---|---|
| P0 | 安防告警、设备故障处置 | 立即执行，必要时预留专用资源 |
| P1 | 实时语音、人机交互 | 低排队时间和低首 Token 延迟 |
| P2 | 普通问答、办公助手 | 默认服务等级 |
| P3 | 文档分析、报表生成 | 可容忍一定排队时间 |
| P4 | 索引构建、离线摘要 | 仅在资源空闲时执行 |

#### FR-4.3：公平调度

**The system shall** 组合使用以下公平调度机制，防止低优先级任务长期饥饿：

- 加权公平队列。
- 租户或应用并发上限。
- 用户并发上限。
- 优先级老化（等待越久的任务逐步提升权重）。
- 长短任务分离。
- 实时任务和批处理任务使用独立执行槽位。
- 大上下文请求设置更高的资源权重。

#### FR-4.4：并发与配额配置

**The system shall** 支持全局、应用级和用户级的并发与配额配置，包括：

- 全局最大运行任务数和最大排队任务数。
- 每个应用的最大运行任务数、最大排队任务数和允许优先级范围。
- 每个用户的默认最大运行任务数和每分钟请求上限。

#### FR-4.5：显存准入

**Before** 任务进入推理服务，**the system shall** 估算以下资源：

- 模型权重占用。
- 输入上下文对应的 KV Cache。
- 预期输出对应的 KV Cache。
- 并发批次的临时显存。
- 图像、音频等多模态编码占用。
- 保留的安全余量。

**When** 预计资源不足，**the system shall** 执行排队、减少输出长度、切换量化模型、切换小模型、转发到其他节点或拒绝请求，而不是冒险提交后等待 OOM。

#### FR-4.6：连续批处理控制

**The system shall** 对支持连续批处理的推理引擎进行以下限制：

- 每个批次的最大请求数。
- 总输入 Token。
- 总预估生成 Token。
- 实时任务允许等待成批的最长时间。
- 超长请求对其他请求的影响。

实时场景优先保障首 Token 延迟，离线任务可适当等待以提升批处理效率。

#### FR-4.7：模型驻留策略

**The system shall** 将模型分为四类驻留策略：

- **常驻模型** — 设备启动后加载，不因普通压力卸载。
- **按需模型** — 有任务时加载，空闲达到阈值后卸载。
- **受限模型** — 只有管理员或指定应用能够触发加载。
- **禁止模型** — 当前硬件条件或安全策略下不能加载。

调度器应避免模型频繁装入和卸载，根据最近使用频率、模型加载成本、任务队列和显存压力进行决策。

---

### FR-5：连接、超时与取消控制

#### FR-5.1：分层超时

**The system shall** 为每个请求配置以下分层超时，不得只设置一个笼统的调用超时：

| 超时类型 | 含义 | 触发行为 |
|---|---|---|
| `connect_timeout` | 客户端建立连接的最长时间 | 连接失败，不创建推理任务 |
| `queue_timeout` | 请求允许在队列中等待的时间 | 取消排队并返回忙碌或降级结果 |
| `first_token_timeout` | 开始执行后等待首 Token 的时间 | 取消任务、切换模型或返回超时 |
| `inference_timeout` | 模型实际推理最长时间 | 向推理引擎发送取消信号 |
| `idle_timeout` | 流式连接连续无数据的时间 | 检查模型状态并终止异常连接 |
| `total_timeout` | 从收到请求到请求结束的总时间 | 强制结束整个调用生命周期 |
| `cancel_grace_period` | 发出取消后等待资源释放的时间 | 超过后隔离或重启异常实例 |

#### FR-5.2：取消传播

**When** 发生以下情况时，**the system shall** 触发取消并传播到模型适配器和推理引擎：

- 客户端主动取消。
- HTTP、SSE 或 WebSocket 连接断开。
- 队列等待超时。
- 首 Token 超时。
- 推理或总调用超时。
- 管理员终止任务。
- 应用或用户权限被撤销。
- 设备温度、显存或系统负载进入危险状态。

取消流程必须覆盖网关、队列、调度器、模型适配器和推理引擎。

#### FR-5.3：任务终态

**The system shall** 确保任务最终只能进入以下终态之一：`SUCCEEDED`、`FAILED`、`CANCELLED`、`TIMED_OUT`。

每次状态变化需记录时间、原因、执行节点、模型实例和操作者。

---

### FR-6：任务状态机

**The system shall** 实现以下任务状态机：

| 状态 | 说明 | 可能的后续状态 |
|---|---|---|
| `RECEIVED` | 请求已接收 | `VALIDATING` |
| `VALIDATING` | 正在校验 | `REJECTED` / `QUEUED` |
| `REJECTED` | 鉴权、配额或参数失败（终态） | — |
| `QUEUED` | 准入成功，等待资源 | `TIMED_OUT` / `CANCELLED` / `DISPATCHING` |
| `DISPATCHING` | 获得资源，正在分派 | `RUNNING` / `FAILED` |
| `RUNNING` | 推理实例接受任务 | `STREAMING` / `TIMED_OUT` |
| `STREAMING` | 已返回首个 Token | `SUCCEEDED` / `CANCELLED` / `TIMED_OUT` / `FAILED` |
| `SUCCEEDED` | 正常完成（终态） | — |
| `FAILED` | 推理异常或模型不可用（终态） | — |
| `CANCELLED` | 连接断开或主动取消（终态） | — |
| `TIMED_OUT` | 队列/首 Token/推理/空闲/总时间超时（终态） | — |

---

### FR-7：模型路由与降级

#### FR-7.1：逻辑模型映射

**The system shall** 支持业务应用使用逻辑模型名称（如 `general-chat`、`fast-chat`、`vision-analysis`），由通讯层映射到实际模型实例，使模型替换不影响业务 API。

#### FR-7.2：路由决策依据

**The system shall** 根据以下因素进行模型路由决策：

- 任务类型和输入模态。
- 应用指定的模型能力等级。
- 上下文窗口和预估输出长度。
- 低延迟或高质量要求。
- 数据隐私和出域限制。
- 当前模型队列长度。
- GPU/NPU 使用率与显存余量。
- 模型是否已经加载。
- 模型近期错误率。
- 设备温度和功耗。
- 本地、备用节点和云端调用成本。

#### FR-7.3：降级链

**The system shall** 支持按业务策略配置以下降级顺序：

1. 同模型的其他本地实例。
2. 同一设备上的小型或量化模型。
3. 其他边缘算力节点。
4. 返回缓存结果或规则化结果。
5. 云端模型。
6. 明确返回系统繁忙。

降级不能绕过数据安全策略。每次降级须在响应元数据和审计日志中记录实际使用的模型及原因。

---

### FR-8：可靠性机制

#### FR-8.1：幂等控制

**The system shall** 支持客户端提交 `idempotency_key`，在有效期内相同租户、应用和幂等键只能创建一个任务，重复请求返回原任务状态或结果。

#### FR-8.2：重试策略

**The system shall** 在以下情况执行有限重试：

- 尚未开始推理时节点连接失败。
- 模型实例正在重启。
- 调度器可以安全切换到等价实例。
- Embedding、分类等确定性或近似幂等任务失败。

**The system shall not** 在以下情况自动重试（除非业务策略明确授权）：

- 已经向客户端输出部分 Token。
- 工具调用可能产生外部副作用。
- 已超过总调用时限。
- 请求包含一次性凭证。
- 重新生成可能导致业务结果不一致。

#### FR-8.3：熔断

**When** 某模型实例在窗口期内出现连续错误、高首 Token 延迟或频繁 OOM，**the system shall** 暂时将其从路由池移除，进入半开检测状态。熔断范围可分模型实例、设备节点、云端供应商和具体 API。

#### FR-8.4：背压

**When** 系统处理能力低于请求进入速度，**the system shall** 按以下顺序采取背压措施：

1. 限制低优先级新请求。
2. 缩短低优先级队列允许等待时间。
3. 降低单个请求最大输出 Token。
4. 将批处理任务延后。
5. 路由至备用节点或小模型。
6. 返回带 `Retry-After` 的系统繁忙响应。

不得无限扩张队列。

---

### FR-9：安全与数据治理

#### FR-9.1：数据隔离

**The system shall** 确保会话、日志、缓存、向量数据和 KV Cache 都包含租户和用户边界，不得因缓存命中、批处理或模型复用而向其他租户泄露上下文。

#### FR-9.2：数据留存控制

**The system shall** 按数据等级配置以下留存策略：

- 是否保存原始 Prompt。
- 是否保存模型完整输出。
- 日志保留天数。
- 是否允许进入云端。
- 是否允许用于质量评估。
- 是否需要脱敏、加密或仅保存哈希。
- 用户删除请求的执行范围。

#### FR-9.3：密钥管理

**The system shall** 确保云端模型密钥、数据库密码和设备证书不写入代码、请求日志或普通配置文件，使用环境密钥、操作系统密钥链或专用 Secret 管理方案。

---

### FR-10：可观测性与运维

#### FR-10.1：核心指标采集

**The system shall** 采集以下三类指标：

**请求指标：**
- 每秒请求数。
- 成功率、失败率、取消率和超时率。
- P50、P95、P99 总延迟。
- 排队时间和队列长度。
- 首 Token 延迟。
- 输入、输出和总 Token 数。
- 每秒输出 Token 数。
- 各模型和应用的并发数。

**资源指标：**
- GPU/NPU/CPU 使用率。
- 显存总量、已用量和碎片情况。
- KV Cache 使用率和命中率。
- 模型加载、卸载次数和耗时。
- 设备温度、功耗和降频状态。
- 磁盘、内存和网络使用率。

**质量指标：**
- 模型降级率。
- 工具调用成功率。
- 上下文裁剪和摘要触发率。
- 安全策略拦截次数。
- 用户中止率和重新生成率。

#### FR-10.2：调用链与日志

**The system shall** 使用统一 `request_id`、`task_id`、`session_id` 和 `trace_id` 串联以下日志：

- 网关接入日志。
- 上下文组装日志。
- 排队和调度日志。
- 模型推理日志。
- 工具调用日志。
- 降级与重试日志。
- 取消、超时和资源释放日志。

日志默认不完整记录敏感 Prompt，需要排障时通过受控采样、脱敏和短期留存开启详细日志。

#### FR-10.3：告警

**The system shall** 支持以下告警规则：

- P95 首 Token 延迟持续超过阈值。
- 队列使用率超过 80%。
- OOM 或模型进程重启。
- 某模型错误率持续升高。
- GPU 温度或功耗进入危险区间。
- 任务取消后资源未及时释放。
- 云端降级比例异常增加。
- 身份验证失败或策略拦截异常增加。

---

### FR-11：模型适配器

#### FR-11.1：推理引擎适配

**The system shall** 通过模型适配器屏蔽不同推理引擎的协议差异，第一阶段至少适配：

- Ollama。
- vLLM。

后续阶段适配：

- llama.cpp。
- TensorRT-LLM。
- Triton。
- 厂商 NPU 推理框架。
- 云端模型 API。

#### FR-11.2：适配器能力要求

**The system shall** 确保模型适配器支持以下能力（按推理引擎支持情况）：

- 请求提交与流式输出。
- 请求取消信号传递。
- Token 使用量统计。
- KV Cache 管理信息。
- 模型加载/卸载状态查询。
- 连续批处理配置。

---

## 5. 非功能需求

### NFR-1：性能

| 指标 | 要求 |
|---|---|
| 通讯层自身增加的非排队延迟 | ≤ 20～50 ms |
| 空闲设备实时请求排队 | 不因后台任务产生明显排队 |
| 并发上限时行为 | 稳定排队，不发生推理进程级 OOM |
| 队列已满时行为 | 快速返回，不继续消耗连接和内存 |
| 请求取消后资源释放 | 在 `cancel_grace_period` 内释放执行槽位 |

### NFR-2：稳定性

- 推理实例重启时，通讯层仍能对外返回明确状态。
- 单个模型故障不会拖垮所有模型接口。
- Redis、数据库或监控组件短暂异常时有明确降级策略。
- 设备达到温度或显存危险阈值时能停止新任务准入。
- 通讯层重启后能够恢复或正确终结尚未完成的任务状态。

### NFR-3：安全性

- 全链路租户标识，缓存隔离和自动化测试防止跨租户数据泄露。
- 云端降级默认禁止，按数据级别显式授权和审计。
- 日志默认只记录元数据，必要时脱敏采样。
- 优先级权限控制、公平调度和老化机制防止高优先级任务被滥用。

### NFR-4：可扩展性

- 单机部署采用进程内队列和轻量状态存储。
- 任务、模型和节点接口需为多机调度预留扩展空间。
- 通讯层通过模型适配器隔离具体推理框架，框架替换不影响 API。
- 第一阶段不引入复杂分布式组件，保留集群扩展能力。

### NFR-5：可维护性

- 通讯层与推理服务采用独立进程，模型进程崩溃不影响 API 和任务状态。
- 通讯层能检测并重新接入恢复后的推理实例。
- 配置支持热更新或受控重载。

---

## 6. 约束与假设

### 6.1 技术约束

- 第一阶段部署目标为单台边缘算力机。
- 通讯层推荐使用 Go、Rust 或 FastAPI 实现。
- 单机版队列使用进程内优先级队列，会话与配置使用 SQLite。
- 可选共享状态使用 Redis。
- 指标使用 Prometheus，展示使用 Grafana。
- 日志使用结构化 JSON 格式。

### 6.2 业务假设

- 推理引擎支持连续批处理、请求取消、Token 统计和 KV Cache 管理是关键选型因素。
- 边缘设备切换模型可能需要数秒到数十秒。
- 敏感任务默认在本地执行。
- 对于需要持续流式输出的任务，一旦开始执行不适合在节点间迁移。

---

## 7. 验收标准

### 7.1 功能验收

- [ ] 业务应用能够通过统一接口调用至少两种不同推理引擎。
- [ ] 模型替换或版本升级时，业务 API 保持兼容。
- [ ] 可以按应用、用户、模型设置并发和队列上限。
- [ ] 高优先级请求在资源允许时能够优先执行。
- [ ] 上下文超限时能够按策略裁剪、摘要或明确拒绝。
- [ ] 客户端断开后，推理任务能够在规定时间内停止。
- [ ] 能够查询任务状态并主动取消排队中或执行中的任务。
- [ ] 所有终态都有明确错误码和可追踪记录。
- [ ] 敏感数据能够强制仅在本地模型处理。

### 7.2 性能验收

- [ ] 通讯层自身增加的非排队延迟不超过 20～50 ms。
- [ ] 空闲设备上的实时请求不因后台任务产生明显排队。
- [ ] 达到并发上限时系统稳定排队，不发生推理进程级 OOM。
- [ ] 队列已满时快速返回，不继续消耗连接和内存。
- [ ] 请求取消后在 `cancel_grace_period` 内释放执行槽位。
- [ ] 所有请求都能统计排队时间、首 Token 时间和推理时间。
- [ ] 压力测试期间无任务状态丢失、重复执行或跨租户数据泄露。

### 7.3 稳定性验收

- [ ] 推理实例重启时，通讯层仍能对外返回明确状态。
- [ ] 单个模型故障不会拖垮所有模型接口。
- [ ] Redis、数据库或监控组件短暂异常时有明确降级策略。
- [ ] 设备达到温度或显存危险阈值时能停止新任务准入。
- [ ] 通讯层重启后能够恢复或正确终结尚未完成的任务状态。

---

## 8. 分阶段实施计划

### 第一阶段：最小可用版本（MVP）

1. OpenAI 兼容的文本生成接口（`/v1/chat/completions`）。
2. API Key 或 JWT 鉴权。
3. 单机优先级队列。
4. 应用级和模型级并发限制。
5. 上下文 Token 预算与基础裁剪。
6. 队列、首 Token、推理和总调用超时。
7. SSE 流式输出。
8. 客户端断开后的推理取消。
9. Ollama 或 vLLM 模型适配器。
10. 请求、Token、延迟、错误和 GPU 指标。

### 第二阶段：增强治理能力

1. 会话持久化与历史摘要。
2. Redis 任务状态和幂等控制。
3. 动态模型路由和小模型降级。
4. 资源准入与显存估算。
5. 连续批处理调优。
6. 模型驻留和自动卸载。
7. 熔断、有限重试和背压。
8. 管理后台和实时监控大盘。

### 第三阶段：多节点与多模态

1. 多台边缘算力机统一调度。
2. 节点注册、心跳和能力上报。
3. 视觉、语音和多模态统一接口。
4. WebSocket 实时双向通信。
5. 本地、备用节点和云端分级路由。
6. 多租户计量、配额和成本分析。
7. 灰度发布、模型版本管理和效果评估。

---

## 9. 关键风险与应对

| 风险 | 可能影响 | 应对措施 |
|---|---|---|
| 显存估算不准确 | OOM、模型崩溃 | 保留安全余量，结合历史数据动态修正 |
| 队列过长 | 请求最终超时、内存增长 | 队列上限、等待超时和背压 |
| 取消能力不完整 | 连接断开后仍消耗算力 | 选择支持取消的引擎，设置隔离和强制恢复机制 |
| 模型频繁换入换出 | 延迟抖动、磁盘和显存压力 | 模型驻留策略和加载成本感知调度 |
| 自动重试产生重复结果 | 重复推理或外部副作用 | 幂等键、状态检查和有限重试 |
| 上下文跨租户泄露 | 严重安全事故 | 全链路租户标识、缓存隔离和自动化测试 |
| 云端降级导致数据出域 | 合规风险 | 默认禁止，按数据级别显式授权和审计 |
| 日志记录完整 Prompt | 敏感信息泄露 | 默认只记录元数据，必要时脱敏采样 |
| 高优先级任务被滥用 | 普通任务长期饥饿 | 优先级权限控制、公平调度和老化机制 |

---

## 10. 术语表

| 术语 | 定义 |
|---|---|
| AI 通讯层 / Edge AI Gateway | 在业务应用与推理服务之间的统一控制面 |
| 逻辑模型 | 业务应用使用的抽象模型名称，如 `general-chat` |
| 实际模型 | 逻辑模型映射到的具体模型实例，如 `qwen3-8b-int4` |
| 执行槽位 | 分配给一个推理任务的并发资源单位 |
| KV Cache | 推理引擎的键值缓存，用于加速生成 |
| 首 Token 延迟 | 从请求开始执行到返回第一个 Token 的时间 |
| 优先级老化 | 等待越久的任务逐步提升调度权重 |
| 常驻模型 | 设备启动后加载，不因普通压力卸载的模型 |
| 幂等键 | 客户端提交的唯一标识，防止重复请求触发重复推理 |
| 背压 | 系统过载时向上游施加压力，限制请求进入速度 |