初始提交：边缘AI算力机统一AI通讯层

0-req.md

@@ -0,0 +1,777 @@
+# 边缘 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 的时间 |
+| 优先级老化 | 等待越久的任务逐步提升调度权重 |
+| 常驻模型 | 设备启动后加载，不因普通压力卸载的模型 |
+| 幂等键 | 客户端提交的唯一标识，防止重复请求触发重复推理 |
+| 背压 | 系统过载时向上游施加压力，限制请求进入速度 |