企业官网建设流程全解析

1. 这不是玄幻小说，而是一套面向大模型服务的轻量级网关架构实践

“荒天帝炼大模型网关”这个标题乍看像某部热门仙侠小说的同人设定，但拆开来看——它其实是一套用修真体系隐喻构建的、专为中小团队设计的大模型服务网关落地路径。我带过三个AI工程化项目，从零搭建过七套推理服务中台，最深的体会是：90%的团队卡在“怎么把一个跑通的LLM demo，变成能被业务系统稳定调用的API”。不是模型不行，而是中间那层“网关”太薄、太脆、太难维护。所谓“搬血境”，不是修炼气血，而是把原始模型输出的token流、logit张量、prompt模板、鉴权逻辑、限流策略这些“血液级”的底层能力，从模型容器里安全、可控、可观测地搬运出来；“狻猊宝术”也不是神兽法诀，而是指代一种基于HTTP/2 + Server-Sent Events（SSE）的流式响应封装技术，能像狻猊吐焰一样稳定喷出结构化JSON chunk；而“逆向筑基”，说白了就是不从零写网关框架，而是反向解构现有开源网关（如FastAPI + Uvicorn + LiteLLM）的请求生命周期，在关键节点打补丁、插钩子、做裁剪——用最小改动获得最大可用性。这套方法特别适合三类人：刚跑通Qwen3或DeepSeek-V3但还没法上线的算法同学；手握LangChain但被OpenAI Rate Limit搞崩溃的业务后端；以及想用本地模型替代云API却苦于没有统一入口的产品经理。它不追求高并发万级QPS，但保证每次请求都带trace_id、每条流式响应都可中断、每个模型切换都不用改前端代码。下面我就以“第1境-搬血境”为起点，把这套网关的实操骨架一节一节拆给你看。

2. 网关设计核心思路：为什么放弃Kong/Nginx，选择“逆向筑基”路线

2.1 传统网关在大模型场景下的三大硬伤

我去年帮一家教育公司做AI助教系统时，第一版就用了Kong+PostgreSQL方案。表面看很规范：Kong负责路由、JWT鉴权、限流，后端接多个模型服务（ChatGLM、Qwen、本地部署的Phi-3）。结果上线三天就崩了两次。问题不在模型，而在网关本身：

• 流式响应被截断：Kong默认缓冲整个响应体再转发，而大模型的SSE流式输出需要逐chunk透传。我们试过调大proxy_buffer_size和关闭proxy_buffering，但Kong的Lua插件对text/event-streamMIME类型的处理有竞态，偶尔会丢掉前两个chunk，导致前端解析JSON失败报错“Unexpected token”。

• 上下文状态无法穿透：用户连续发5条消息，理想情况是保持同一个session_id走同一台GPU机器。但Kong的负载均衡策略（round-robin）和session sticky配置在HTTP/2下失效，因为gRPC over HTTP/2的连接复用机制让Kong无法识别真正的“会话粒度”。

• 调试成本指数级上升：一次请求经过Kong→Auth Service→Model Router→vLLM Engine四层，日志分散在四个服务里。查一个超时问题要翻遍四套ELK索引，trace_id在Kong里生成，到vLLM里就变成另一个ID，链路追踪形同虚设。

后来我们砍掉Kong，用Python重写网关层，只保留最核心的三件事：协议转换、身份透传、流控熔断。开发周期从两周压缩到三天，线上故障率下降87%。这验证了一个事实：大模型网关不是越重越好，而是越贴近模型运行时越稳。

2.2 “逆向筑基”的本质：在LiteLLM之上做精准外科手术

LiteLLM是个好工具，它用统一API封装了OpenAI、Anthropic、Ollama等二十多种后端。但直接暴露LiteLLM给业务方，等于把厨房门敞开——所有模型参数、温度值、top_p、max_tokens全由前端控制，一个恶意请求就能拖垮整台GPU。我们的“逆向筑基”策略，就是把LiteLLM当成一块“原石”，不打磨成工艺品，而是用手术刀切出三块关键模块：

• 前置熔断器（Blood-Flow Gate）：在LiteLLM的completion()函数调用前插入校验逻辑。比如检测messages数组长度是否超过预设阈值（防prompt注入）、model参数是否在白名单内（禁用未授权模型）、user_id是否匹配租户配额（多租户隔离）。这部分代码只有47行，但挡住了83%的异常请求。

• 流式响应增强器（SSE Enchanter）：LiteLLM原生支持SSE，但返回的chunk格式是纯文本event:data。我们把它升级为标准JSON chunk，并嵌入业务字段：

  event: message data: {"id":"chat_abc123","object":"chat.completion.chunk","created":1715678901,"model":"qwen2-7b","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"finish_reason":null}]}

  关键改动是增加model字段（方便前端识别当前调用模型）、created时间戳（用于计算端到端延迟）、以及finish_reason的显式传递（避免前端靠content为空判断结束）。

• 上下文锚点注入器（Context Anchor）：当请求头带X-Session-ID: sess_xyz时，自动在prompt末尾追加<|session_id|>sess_xyz<|end_session_id|>标记。vLLM引擎侧通过自定义tokenizer识别该标记，在KV Cache中为不同session分配独立slot，实现真正的会话级上下文隔离。这个技巧让我们用单卡A100支撑了200+并发会话，而不用上Redis缓存历史。

这种“逆向”不是推翻重来，而是像老中医号脉——先摸清LiteLLM的经络走向（源码里litellm/main.py的completion()函数调用链），再在气穴（关键hook点）下针。我们没动一行LiteLLM核心代码，所有增强都通过custom_llm_provider和litellm.success_callback实现，升级LiteLLM版本时只需检查callback签名是否变更。

2.3 为什么选“搬血境”作为第一境？——聚焦最痛的底层数据流

修真小说里“搬血境”是打基础的第一步，要锤炼血液质量、疏通经脉。对应到网关建设，就是解决三个最原始的问题：

1. 请求怎么进来？—— 不是简单监听8000端口，而是定义清晰的入口契约：哪些header必传（X-User-ID,X-Tenant-ID），哪些query参数允许（stream=true必须小写，format=json仅支持两种值）；
2. 数据怎么流动？—— 明确token流、logit张量、错误码三条数据线的走向：token流走SSE通道，logit张量走独立metrics接口供监控，错误码统一用RFC 7807 Problem Details格式；
3. 血怎么回流？—— 指响应如何反馈给调用方：成功时返回标准OpenAI兼容JSON，失败时返回带type、title、status、detail的Problem JSON，并确保status严格对应HTTP状态码（429对应rate limit，403对应quota exceeded）。

这三件事看似简单，但90%的网关事故都源于其中某一条线断裂。比如某次线上故障，前端报“Connection closed”，排查发现是网关在stream=false时误用了SSE header，导致Chrome浏览器主动断连。这种细节，只有亲手“搬过血”的人才会刻进DNA。

3. 核心细节解析：搬血境四大支柱与实操要点

3.1 支柱一：协议层净化——HTTP/1.1与HTTP/2的混合兼容设计

大模型服务面临一个现实矛盾：前端Web应用习惯HTTP/1.1 + SSE，而内部模型服务（如vLLM）推荐HTTP/2 + gRPC。如果强制统一协议，要么前端重写fetch逻辑，要么后端降级性能。我们的解法是“双协议入口”：

• HTTP/1.1入口（/v1/chat/completions）：专供浏览器调用。启用Transfer-Encoding: chunked，响应头固定设置：

  Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive X-Accel-Buffering: no

  最后一行X-Accel-Buffering: no是Nginx反向代理的关键开关，否则Nginx会缓存整个SSE流再吐给前端。

• HTTP/2入口（/v2/chat/completions）：专供iOS/Android App及内部微服务调用。用curl -H "Accept: application/json"测试时，自动降级为普通JSON响应；用curl --http2 -H "Accept: application/grpc"则触发gRPC二进制协议。后端vLLM通过--enable-http-2启动参数支持此模式。

实操中最大的坑是HTTP/2的ALPN协商失败。我们遇到过iOS 16设备无法建立HTTP/2连接，抓包发现客户端发送ALPN列表为h2,http/1.1，但Nginx默认只支持h2。解决方案是在Nginx配置中显式声明：

ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; # 关键：显式指定ALPN ssl_alpn_protocols h2 http/1.1;

这个配置让Nginx在TLS握手时明确告诉客户端“我支持h2和http/1.1”，iOS设备就能顺利协商出HTTP/2连接。没这行配置，看似能连上，实则降级为HTTP/1.1，白白浪费HTTP/2的多路复用优势。

提示：不要迷信“HTTP/2一定更快”。在单次短请求场景下，HTTP/1.1的TCP连接复用可能比HTTP/2的头部压缩更省资源。我们实测发现，当平均请求时长<800ms时，HTTP/1.1吞吐量反而高12%，因为省去了HTTP/2帧解析开销。

3.2 支柱二：身份透传——从JWT到租户上下文的无损搬运

很多团队用JWT做鉴权，但常犯一个致命错误：把JWT payload直接当用户信息用。比如解析出{ "user_id": "u123", "role": "admin" }就完事。问题在于，大模型服务需要更细粒度的上下文：

• tenant_id：决定调用哪个模型集群（金融租户用Qwen2-72B，教育租户用Phi-3）；
• quota_used：实时配额消耗，用于动态限流；
• allowed_models：白名单模型列表，防止越权调用。

我们的做法是：网关收到JWT后，不直接解码，而是调用内部Auth Service的/verify-jwt接口，传入JWT和请求路径（如/v1/chat/completions），返回一个 enriched context 对象：

{ "user_id": "u123", "tenant_id": "t456", "role": "teacher", "quota_used": 1247, "quota_limit": 5000, "allowed_models": ["qwen2-7b", "phi-3"], "session_id": "sess_xyz" }

这个对象被序列化为X-Contextheader（base64编码），透传给后端模型服务。vLLM引擎侧通过middleware解码，提取tenant_id选择对应模型，用quota_used/quota_limit计算当前请求权重，再结合allowed_models校验model参数。

为什么不用Redis缓存JWT解析结果？因为Redis网络延迟（平均3ms）在高并发下会成为瓶颈。我们实测，当QPS>200时，Redis调用耗时占整个请求的18%。改为同步HTTP调用Auth Service（部署在同一K8s namespace，延迟<0.2ms），整体P99延迟下降41%。代价是Auth Service需支持水平扩展，但这比优化Redis更可控。

3.3 支柱三：流控熔断——基于令牌桶与滑动窗口的双保险

大模型服务的流量特征很特殊：突发性强（上课铃响瞬间2000人提问）、持续时间长（一个完整对话可能持续5分钟）、资源消耗不均（思考型问题比闲聊消耗3倍GPU显存）。单一限流策略必然失灵。我们采用“令牌桶+滑动窗口”双控：

• 令牌桶（Token Bucket）：控制瞬时峰值。每个tenant_id分配独立桶，容量100令牌，每秒补充10令牌。每次请求消耗1令牌（简单计数），超限时返回429 Too Many Requests并带Retry-After: 1头。这个桶防的是DDoS式攻击，比如脚本疯狂刷/health接口。

• 滑动窗口（Sliding Window）：控制持续负载。统计最近60秒内该租户的总请求数、总tokens消耗、总GPU秒消耗（vLLM上报的gpu_seconds指标）。当任一指标超阈值，触发熔断：

  • 请求总数>500 → 返回503 Service Unavailable，Header带X-RateLimit-Reset: 60；
  • tokens消耗>100万 → 自动降级到小模型（如从Qwen2-72B切到Qwen2-7B）；
  • GPU秒消耗>300 → 暂停新请求，已排队请求继续处理。

关键实现细节：滑动窗口数据存在内存里（concurrent.futures.ThreadPoolExecutor管理的dict），每秒滚动一次。为什么不存Redis？因为Redis的ZREMRANGEBYSCORE操作在百万级key下会阻塞主线程。内存方案牺牲了分布式一致性，但换来亚毫秒级响应——对网关来说，这是值得的。

注意：熔断阈值不能写死。我们用Prometheus指标动态计算：rate(http_request_total{job="model-gateway"}[5m])作为基准QPS，乘以1.5作为令牌桶速率。这样当业务流量自然增长时，限流阈值自动上浮，避免人为调整。

3.4 支柱四：可观测性埋点——从“黑盒”到“透明血管”

没有可观测性的网关，就像没有血压计的医生。我们定义了五个黄金指标，全部通过OpenTelemetry Collector采集：

特别要提gateway.stream.chunks.sent。这个指标解决了长期困扰我们的“前端收不到最后chunk”问题。我们发现，当vLLM因OOM kill进程时，SSE流会静默中断，前端永远等不到finish_reason="stop"。于是我们在网关层加了一条规则：如果10秒内未收到新chunk，且finish_reason仍为null，则主动发送一个终止chunk：

event: message data: {"choices":[{"finish_reason":"aborted"}]}

同时打点gateway.stream.abortedcounter。这个简单的补丁，让前端超时逻辑从“猜”变成“确定”，错误率下降63%。

4. 实操过程详解：从零搭建搬血境网关的七步筑基法

4.1 第一步：环境准备与依赖锁定（30分钟）

别跳过这步！我见过太多团队在pip install litellm后直接开干，结果两周后发现LiteLLM升级到0.2.0，success_callback签名变了，整个网关挂掉。我们的环境清单如下：

• Python 3.10.12（必须，vLLM 0.4.2要求Python>=3.10）
• pip-tools管理依赖（不是requirements.txt）
• 核心依赖精确锁定：

  # requirements.in litellm==1.42.0 fastapi==0.111.0 uvicorn[standard]==0.29.0 opentelemetry-api==1.24.0 opentelemetry-sdk==1.24.0 prometheus-client==0.18.0

执行pip-compile requirements.in生成requirements.txt，再pip install -r requirements.txt。关键点：litellm==1.42.0是经过我们压测验证的稳定版本，它修复了0.41.x中SSE流在高并发下的内存泄漏问题（GitHub issue #3821）。

实操心得：在Dockerfile里用RUN pip install --no-cache-dir -r requirements.txt，而不是COPY requirements.txt . && pip install -r requirements.txt。前者确保每次构建都重新解析依赖树，后者可能因缓存导致旧版本残留。

4.2 第二步：创建网关主程序（src/gateway/main.py）

这不是Hello World，而是定义网关骨架。核心代码结构如下：

from fastapi import FastAPI, Request, Response, HTTPException from fastapi.middleware.cors import CORSMiddleware import litellm from litellm import completion from litellm.proxy._types import UserRequest import json import time from typing import Dict, Any app = FastAPI(title="荒天帝网关-搬血境") # CORS配置（生产环境需细化origin） app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) @app.post("/v1/chat/completions") async def chat_completions(request: Request): start_time = time.time() try: # 1. 解析请求体（必须读取一次，后续不能再读） body = await request.body() payload = json.loads(body.decode()) # 2. 提取并校验必要字段 model = payload.get("model") if not model or model not in ["qwen2-7b", "phi-3"]: raise HTTPException(status_code=400, detail="Invalid model") # 3. 注入上下文（从header获取enriched context） context = get_context_from_header(request.headers) # 4. 构建LiteLLM调用参数 litellm_params = { "model": model, "messages": payload.get("messages", []), "stream": payload.get("stream", False), "temperature": payload.get("temperature", 0.7), "max_tokens": min(payload.get("max_tokens", 1024), 2048), # 硬限制 } # 5. 执行调用（关键：注册success/failure callback） response = completion(**litellm_params) # 6. 处理响应（流式/非流式分支） if payload.get("stream"): return StreamingResponse( stream_response(response, context), media_type="text/event-stream" ) else: return JSONResponse(content=normalize_response(response, context)) except Exception as e: # 统一错误处理 log_error(e, start_time, context) raise HTTPException(status_code=500, detail=str(e)) # 后续实现get_context_from_header、stream_response等函数...

这段代码的价值不在功能，而在契约意识：它明确定义了网关的输入边界（只接受model在白名单）、输出格式（StreamingResponse或JSONResponse）、错误码体系（400/500）。所有后续增强都围绕这个骨架展开，不会破坏原有接口。

4.3 第三步：实现上下文提取器（src/gateway/context.py）

这是“搬血”的核心动作——把散落在各处的身份信息聚合成一个context对象。代码逻辑分三层：

1. Header解析层：从X-Contextheader读取base64字符串，解码为JSON；
2. Fallback校验层：如果X-Context不存在，尝试从Authorization: Bearer <jwt>解析，但只取user_id和tenant_id，其他字段置空；
3. 租户增强层：调用auth_service.enrich_context(context)，补充quota_used、allowed_models等动态字段。

关键细节：X-Contextheader必须用base64编码，而不是JWT。因为JWT可能含.字符，某些代理服务器（如AWS ALB）会截断。Base64编码确保header值是URL安全的ASCII字符串。

import base64 import json import requests from fastapi import Request def get_context_from_header(headers: dict) -> dict: context_str = headers.get("X-Context") if not context_str: # Fallback to JWT auth = headers.get("Authorization", "") if auth.startswith("Bearer "): jwt = auth[7:] # 简单解析JWT header.payload（不验签，只取字段） try: payload_b64 = jwt.split(".")[1] payload = json.loads(base64.urlsafe_b64decode(payload_b64 + "==")) return { "user_id": payload.get("sub"), "tenant_id": payload.get("tenant_id", "default"), "allowed_models": ["qwen2-7b"] } except: pass raise HTTPException(status_code=401, detail="Missing X-Context or Authorization header") try: context_bytes = base64.b64decode(context_str) context = json.loads(context_bytes.decode()) # 调用Auth Service增强 enhanced = requests.post( "http://auth-service:8000/enrich-context", json=context, timeout=0.5 ).json() return enhanced except Exception as e: raise HTTPException(status_code=401, detail=f"Context decode failed: {e}")

4.4 第四步：构建流式响应增强器（src/gateway/stream.py）

这才是“狻猊宝术”的真身。LiteLLM的原生SSE流是这样的：

data: {"choices":[{"delta":{"content":"Hello"}}]} data: {"choices":[{"delta":{"content":" world!"}}]} data: {"choices":[{"finish_reason":"stop"}]}

我们的增强目标是：

• 每个chunk都带id、model、created；
• content字段必须是字符串，不能是None；
• 最终chunk必须显式包含finish_reason。

实现代码：

from starlette.responses import StreamingResponse import json import time from typing import AsyncGenerator async def stream_response(litellm_response, context: dict) -> AsyncGenerator[bytes, None]: # 发送open event（可选，用于前端心跳） yield b'event: open\ndata: {"status":"connected"}\n\n' for chunk in litellm_response: # 标准化chunk standardized = { "id": f"chat_{int(time.time())}", "object": "chat.completion.chunk", "created": int(time.time()), "model": context.get("model", "unknown"), "choices": [] } # 处理choices for choice in chunk.get("choices", []): delta = choice.get("delta", {}) # 确保content是字符串 content = delta.get("content") or "" if not isinstance(content, str): content = str(content) standardized_choice = { "index": choice.get("index", 0), "delta": { "role": delta.get("role", "assistant"), "content": content }, "finish_reason": choice.get("finish_reason") } standardized["choices"].append(standardized_choice) # 序列化并yield yield f"event: message\ndata: {json.dumps(standardized)}\n\n".encode() # 强制发送结束事件（防前端等待） yield f"event: close\ndata: {json.dumps({'status': 'completed'})}\n\n".encode()

实操心得：yield前不要加await asyncio.sleep(0)！这是新手常犯的错误，以为要“让出控制权”，结果导致SSE流被缓冲，前端收不到实时响应。AsyncGenerator的yield本身就是异步的，加sleep反而引入延迟。

4.5 第五步：集成熔断与限流（src/gateway/ratelimit.py）

我们用aiolimiter库实现令牌桶，用collections.deque实现滑动窗口。关键是要让两者协同工作：

from aiolimiter import AsyncLimiter from collections import deque import time from typing import Dict, Deque # 全局限流器（按tenant_id隔离） limiters: Dict[str, AsyncLimiter] = {} # 滑动窗口数据（tenant_id -> deque of (timestamp, tokens)） windows: Dict[str, Deque] = {} def get_limiter(tenant_id: str) -> AsyncLimiter: if tenant_id not in limiters: # 每租户100令牌/秒 limiters[tenant_id] = AsyncLimiter(100, 1) return limiters[tenant_id] def check_sliding_window(tenant_id: str, tokens: int) -> bool: now = time.time() window = windows.setdefault(tenant_id, deque()) # 清理60秒前的数据 while window and window[0][0] < now - 60: window.popleft() # 计算当前窗口tokens总和 total_tokens = sum(item[1] for item in window) if total_tokens + tokens > 1_000_000: # 100万tokens/60秒 return False # 记录本次请求 window.append((now, tokens)) return True # 在main.py的chat_completions中调用： # await get_limiter(context["tenant_id"]).acquire() # if not check_sliding_window(context["tenant_id"], estimated_tokens): # raise HTTPException(status_code=503, detail="Tenant quota exceeded")

4.6 第六步：添加可观测性（src/gateway/telemetry.py）

OpenTelemetry不是摆设，要让它真正指导运维。我们只采集最关键的五个指标，全部通过Counter、Histogram、Gauge类型上报：

from opentelemetry import metrics from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.exporter.prometheus import PrometheusMetricReader from prometheus_client import start_http_server # 初始化Meter reader = PrometheusMetricReader() provider = MeterProvider(metric_readers=[reader]) metrics.set_meter_provider(provider) meter = metrics.get_meter("gateway") # 定义指标 request_duration = meter.create_histogram( "gateway.request.duration", unit="ms", description="Duration of HTTP requests" ) tokens_counter = meter.create_counter( "gateway.model.tokens.total", description="Total tokens generated" ) # 在main.py中记录： # request_duration.record(duration_ms, attributes={"tenant_id": context["tenant_id"]}) # tokens_counter.add(output_tokens, attributes={"model": model})

启动Prometheus exporter：

# 在app启动后 start_http_server(port=9090, addr="0.0.0.0")

这样访问http://localhost:9090/metrics就能看到所有指标，配合Grafana画出实时仪表盘。

4.7 第七步：编写健康检查与部署脚本（Dockerfile + docker-compose.yml）

生产环境不能靠uvicorn src.gateway.main:app --reload。我们的Dockerfile极致精简：

FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY src/ . # 创建非root用户 RUN addgroup -g 1001 -f appgroup && adduser -S appuser -u 1001 USER appuser EXPOSE 8000 CMD ["uvicorn", "gateway.main:app", "--host", "0.0.0.0:8000", "--port", "8000", "--workers", "4"]

docker-compose.yml确保网关与Auth Service、Prometheus同网络：

version: '3.8' services: gateway: build: . ports: - "8000:8000" environment: - PYTHONUNBUFFERED=1 depends_on: - auth-service - prometheus auth-service: image: auth-service:latest # ... 配置省略 prometheus: image: prom/prometheus:latest volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml

5. 常见问题与排查技巧实录：搬血境实战踩坑全记录

5.1 问题一：前端收到SSE流，但JSON.parse()报错“Unexpected end of input”

现象：浏览器控制台频繁报错，抓包发现SSE响应体最后几行缺失，data:字段不完整。

根因分析：Nginx默认开启proxy_buffering，它会等待整个响应结束才转发给客户端。而SSE流是持续输出的，Nginx在缓冲区满或超时后强行截断流。

解决方案：在Nginx配置中彻底关闭缓冲：

location /v1/ { proxy_pass http://gateway:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 关键三行 proxy_buffering off; proxy_cache off; proxy_buffer_size 128k; }

proxy_buffer_size 128k是必须的，否则Nginx会用默认4k缓冲区，导致大chunk被截断。

独家技巧：在网关层加一个“心跳保活”机制。在SSE流空闲5秒后，自动发送一个注释事件：

# 在stream_response函数中 last_send = time.time() while True: # ... 读取chunk逻辑 if time.time() - last_send > 5: yield b': heartbeat\n\n' last_send = time.time()

: heartbeat是SSE注释语法，浏览器忽略，但能防止代理服务器因超时关闭连接。

5.2 问题二：同一tenant_id的请求被路由到不同GPU节点，上下文丢失

现象：用户连续提问，第二条回复完全不记得第一条内容。

根因分析：K8s Service的ClusterIP默认使用iptables模式，其session affinity（sticky session）只对TCP连接有效，而HTTP/2的多路复用让多个请求共享一个TCP连接，导致affinity失效。

解决方案：改用IPVS模式，并启用clientIP会话保持：

apiVersion: v1 kind: Service metadata: name: model-gateway spec: sessionAffinity: ClientIP sessionAffinityConfig: clientIP: timeoutSeconds: 10800 # 3小时 # ... 其他配置

但IPVS模式需K8s集群支持。更通用的解法是：在网关层生成X-Session-ID，并用X-Session-ID做一致性哈希路由。我们用hashlib.md5(tenant_id.encode()).hexdigest()[:8]生成8位hash，映射到32个虚拟节点，再mod GPU节点数，确保同一tenant_id永远落到同一台机器。

5.3 问题三：litellm completion()调用后，CPU飙升100%，但GPU利用率几乎为0

现象：网关Pod CPU持续100%，nvidia-smi显示GPU显存占用正常，但util%为0。

根因分析：LiteLLM的completion()函数在stream=False时，会把整个响应体加载到内存再返回。当模型输出很长（如10000 tokens），Python的JSON序列化会吃光CPU。

解决方案：强制流式处理。即使前端传stream=false，网关也以stream方式调用LiteLLM，然后在内存中拼接chunk：

if not payload.get("stream"): # 内部转为stream调用 litellm_params["stream"] = True chunks = [] for chunk in completion(**litellm_params): chunks.append(chunk) # 拼接成完整response full_response = merge_chunks(chunks) return JSONResponse(content=full_response)

merge_chunks()函数只合并choices数组，不涉及大字符串拼接，CPU消耗下降90%。

5.4 问题四：Prometheus指标显示gateway.request.durationP99高达5秒，但vLLM日志显示模型推理只要800ms

现象：网关延迟高，但模型侧延迟正常，问题定位困难。

根因分析：gateway.request.duration统计的是从FastAPI收到请求到返回响应的总时间，包括：网络传输、JWT解析、限流等待、SSE流式write耗时。而vLLM日志只记录模型推理时间。

**