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