logo

内网部署27B大模型,搭建长文档与代码审查服务

作者:渣渣辉2026.11.16 11:57浏览量:0

简介:本文说明如何在内网服务器部署约270亿参数的开源大模型,并以HTTP接口提供长文档与代码审查服务。内容涵盖显存估算、固定版本环境、API Key鉴权与限流、上线验证和日常运维,帮助团队在数据不出内网的前提下,搭建可核对、可排错的审阅服务。

一、适用范围与前置条件

本文说明如何在内网服务器上部署约270亿参数的开源稠密模型,并通过HTTP接口为文档管理系统、代码仓库或自动化流水线提供长文档理解与代码审查能力。调用方使用API Key访问服务,文档和代码不离开内网。

部署前先确认三件事。第一,所选模型的许可证允许内部使用。第二,模型的名称、最大上下文长度和聊天模板,以模型官方仓库的说明为准。第三,服务器资源满足第二节的估算结果。

硬件方面,准备一张或多张NVIDIA GPU,显存总量不低于第二节计算出的总需求,并预留余量。驱动、CUDA和容器运行时的版本需与推理框架的要求一致。磁盘需容纳模型权重和日志。网络上只开放网关端口,推理后端只监听本机回环地址。

读者需要掌握Linux基本命令、容器概念,以及HTTP接口调用。

部分聊天模板不支持system角色。遇到这种情况,把系统提示与审查材料合并到user消息中,示例见第四节。

模型会漏报,也会误报。本文不承诺任何准确率。模型输出的每条问题都要附上原文位置,由人工核对。法律结论、安全漏洞定级、代码合并决定和对外合规判断不交给本服务完成,这些结论必须由具备资质的人员负责。

评测口径

上线前,用本单位人工标注的样本测量效果。建议样本不少于200份,覆盖版本号不一致、边界条件遗漏等主要问题类型,并保留一部分无问题样本。

召回率 = 正确发现的问题数 ÷ 人工标注的问题总数。

误报率 = 模型报出但经人工确认无效的问题数 ÷ 模型报出的问题总数。

验收阈值由团队根据业务风险自行确定。模型、量化方案或推理框架版本变化后,都要用同一批样本重新测量。

二、显存怎么估?

显存由三部分组成:模型权重、KV Cache,以及框架运行和激活值的开销。

权重占用

权重占用 = 参数量 × 每参数字节数。以27B参数为例:

  • FP16或BF16(每参数2字节):27×10^9 × 2 ≈ 54 GB
  • 8-bit量化(每参数1字节):约27 GB
  • 4-bit量化(每参数0.5字节):约13.5 GB

这些数字只计算权重本身。量化方案会引入额外的元数据,部分层也可能保留高精度,实际占用以加载后的nvidia-smi读数为准。

量化会带来精度损失。常见方案包括GPTQ、AWQ,以及面向CPU和混合部署的GGUF格式。选定方案后,必须用第一节的人工样本,对比量化前后的召回率和误报率。

KV Cache占用

KV Cache随输入长度和并发数增长。单个token在所有层中占用的字节数为:

每token字节数 = 2 × 层数 × KV头数 × head_dim × 每元素字节数

系数2表示K和V两份缓存。层数、KV头数和head_dim都写在模型目录的config.json中,应以该文件为准。注意这里使用的是KV头数,它可能少于注意力头数(分组查询注意力)。

总KV Cache占用 = 每token字节数 × 序列长度 × 并发请求数

下面用一组假设配置演示计算过程:层数64,KV头数8,head_dim为128,KV Cache使用FP16(每元素2字节)。

  • 每token字节数 = 2 × 64 × 8 × 128 × 2 = 262144字节,即256 KiB
  • 单请求、4k上下文:256 KiB × 4096 ≈ 1 GiB
  • 单请求、32k上下文:256 KiB × 32768 = 8 GiB
  • 4并发、32k上下文:8 GiB × 4 = 32 GiB

以上只是演示。实际计算时,要把参数替换为自己模型config.json中的数值。

总显存与余量

总显存 ≈ 权重 + KV Cache + 框架与激活值开销

框架开销包括CUDA上下文、算子缓存和中间激活值,无法给出固定数值,应在试运行时用监控工具读取。建议用推理框架的显存利用上限参数(例如vLLM的--gpu-memory-utilization)限定占用比例,并为突发流量和显存碎片留出空间。

三、固定版本环境与部署

环境版本

所有版本都要固定并记录。先在测试机上验证通过,再复制到生产机。推荐使用Ubuntu LTS系统,安装与推理框架匹配的NVIDIA驱动和CUDA,安装Docker,并安装nvidia-container-toolkit,使容器可以访问GPU。

依赖写入锁定文件,例如:

  1. # requirements.lock(示例,版本号替换为测试通过的版本)
  2. vllm==<已验证版本>
  3. fastapi==<已验证版本>
  4. uvicorn==<已验证版本>
  5. httpx==<已验证版本>

模型文件放在只读目录,例如/models/review-27b-<日期>/。下载后校验SHA256,并记录来源、许可证文件和下载时间。

启动推理后端

推理后端只监听本机回环地址,外部请求一律经过第四节的网关。示例命令如下,参数需按第二节的估算结果和GPU数量调整:

  1. vllm serve /models/review-27b-20261101 \
  2. --served-model-name review-27b \
  3. --host 127.0.0.1 --port 8000 \
  4. --max-model-len 32768 \
  5. --gpu-memory-utilization 0.90 \
  6. --tensor-parallel-size 2

如果使用量化模型,还要按框架文档添加对应的量化参数,并确认该格式受框架支持。

使用systemd托管

用systemd分别管理推理后端和网关。进程崩溃后可以自动重启,日志也能统一查看。

  1. # /etc/systemd/system/review-llm.service
  2. [Unit]
  3. Description=Review LLM backend
  4. After=network-online.target docker.service
  5. [Service]
  6. ExecStart=/opt/review-llm/bin/start-backend.sh
  7. EnvironmentFile=/etc/review-llm/env
  8. Restart=on-failure
  9. RestartSec=10
  10. [Install]
  11. WantedBy=multi-user.target

环境文件/etc/review-llm/env的属主设为服务账号,权限设为600。服务账号不具备sudo权限,也不能写入模型目录。

四、鉴权限流与推理代码怎么做?

网关结构

网关使用FastAPI实现,监听内网地址。它完成三件事:校验API Key、按调用方限流、把请求转发给推理后端。网关还限制并发数和输出长度,防止单个请求占满显存。如果前面有Nginx,应在Nginx中用client_max_body_size限制请求体大小。

API Key管理

API Key由服务端随机生成,长度不少于32字节,例如用openssl rand -hex 32生成。环境变量REVIEW_API_KEYS保存逗号分隔的密钥列表。每个调用方使用一把密钥,便于单独吊销。密钥不写入代码和仓库,也不写入日志。日志中只记录密钥的哈希前缀。

网关代码

  1. import asyncio
  2. import hashlib
  3. import hmac
  4. import os
  5. import time
  6. import httpx
  7. from fastapi import FastAPI, HTTPException, Request
  8. from fastapi.responses import JSONResponse
  9. UPSTREAM = os.environ.get("UPSTREAM_URL", "http://127.0.0.1:8000")
  10. MODEL_NAME = os.environ.get("MODEL_NAME", "review-27b")
  11. API_KEYS = [k.strip() for k in os.environ["REVIEW_API_KEYS"].split(",") if k.strip()]
  12. RATE_PER_MIN = int(os.environ.get("RATE_PER_MIN", "30"))
  13. MAX_TOKENS_CAP = int(os.environ.get("MAX_TOKENS_CAP", "4096"))
  14. MAX_CONCURRENT = int(os.environ.get("MAX_CONCURRENT", "4"))
  15. app = FastAPI()
  16. _semaphore = asyncio.Semaphore(MAX_CONCURRENT)
  17. _buckets: dict[str, tuple[float, float]] = {}
  18. _lock = asyncio.Lock()
  19. def key_id(key: str) -> str:
  20. return hashlib.sha256(key.encode()).hexdigest()[:12]
  21. def authenticate(request: Request) -> str:
  22. header = request.headers.get("authorization", "")
  23. if not header.startswith("Bearer "):
  24. raise HTTPException(status_code=401, detail="missing api key")
  25. token = header[len("Bearer "):]
  26. matched = None
  27. for key in API_KEYS:
  28. if hmac.compare_digest(token, key):
  29. matched = key
  30. if matched is None:
  31. raise HTTPException(status_code=401, detail="invalid api key")
  32. return key_id(matched)
  33. async def allow(client: str) -> bool:
  34. """令牌桶限流:每分钟补充 RATE_PER_MIN 个令牌。"""
  35. async with _lock:
  36. now = time.monotonic()
  37. capacity = float(RATE_PER_MIN)
  38. tokens, last = _buckets.get(client, (capacity, now))
  39. tokens = min(capacity, tokens + (now - last) * capacity / 60.0)
  40. if tokens < 1:
  41. _buckets[client] = (tokens, now)
  42. return False
  43. _buckets[client] = (tokens - 1, now)
  44. return True
  45. @app.post("/v1/review")
  46. async def review(request: Request):
  47. client = authenticate(request)
  48. if not await allow(client):
  49. raise HTTPException(status_code=429, detail="rate limit exceeded")
  50. payload = await request.json()
  51. messages = payload.get("messages")
  52. if not isinstance(messages, list) or not messages:
  53. raise HTTPException(status_code=400, detail="messages required")
  54. payload["model"] = MODEL_NAME
  55. payload["max_tokens"] = min(int(payload.get("max_tokens", 2048)), MAX_TOKENS_CAP)
  56. async with _semaphore:
  57. async with httpx.AsyncClient(timeout=600) as http:
  58. resp = await http.post(f"{UPSTREAM}/v1/chat/completions", json=payload)
  59. return JSONResponse(status_code=resp.status_code, content=resp.json())
  60. @app.get("/healthz")
  61. async def healthz():
  62. async with httpx.AsyncClient(timeout=5) as http:
  63. resp = await http.get(f"{UPSTREAM}/health")
  64. return {"gateway": "ok", "backend_status": resp.status_code}

限流状态保存在进程内存中,因此网关只能以单进程运行,即uvicorn gateway:app --workers 1。如果将来部署多个网关实例,应把限流计数迁移到Redis等共享存储。

调用示例

  1. curl -s http://gateway.internal:9000/v1/review \
  2. -H "Authorization: Bearer $REVIEW_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{"messages":[{"role":"user","content":"请审查以下文档,并为每条问题附上原文位置。"}],"temperature":0}'

合并system提示

遇到不支持system角色的模板时,把系统提示与材料合并到user消息中:

  1. SYSTEM_PROMPT = "你是一名严谨的代码与文档审阅员。只报告有原文依据的问题,每条问题必须标注原文位置。"
  2. messages = [{"role": "user", "content": f"{SYSTEM_PROMPT}\n\n---\n\n{material}"}]

五、上线验证与日常运维

上线验证

按下列顺序验证,每一步都记录结果:

  1. 访问/healthz,确认网关和后端都返回正常状态。
  2. 不带密钥、带错误密钥各请求一次,应分别返回401。
  3. 用合法密钥连续请求超过限流阈值,应出现429。
  4. 用超长文档请求一次,确认返回的是明确的错误信息,而不是进程退出。
  5. 用人工样本跑完整评测,计算召回率和误报率,与验收阈值比对。

日志与监控

每次请求记录一行结构化日志,包含时间、密钥哈希前缀、输入字符数、输出token数、耗时和状态码。日志不记录文档正文和模型输出,避免敏感内容外泄。

监控重点包括GPU显存占用、等待队列长度、429比例和5xx比例。429比例持续偏高,说明限流阈值或调用方的批量任务需要调整。5xx比例上升,通常意味着显存紧张或后端崩溃。

密钥轮换

轮换时先在REVIEW_API_KEYS中加入新密钥,把新密钥分发给调用方。确认调用方全部切换后,再从列表中移除旧密钥并重启网关。

模型升级与回滚

模型目录按版本保留,例如/models/review-27b-20261101/和/models/review-27b-20260915/。服务通过软链接/models/current指向当前版本。升级时修改软链接并重启后端服务。

回滚时把软链接指回旧版本并重启。回滚的依据是评测指标,而不是单次调用的感觉。每次模型、量化方案或框架版本变化后,都要用同一批人工样本重新测量。

六、常见错误

  • 显存不足(OOM):降低--max-model-len或并发数,或改用量化方案。调整后重新用第二节的公式核算。
  • 上下文超限:后端会返回错误。把长文档按章节或代码文件切分,分批提交。
  • 量化兼容性问题:加载失败时,先核对量化格式是否被当前框架版本支持。
  • API Key硬编码:一经发现,立即吊销该密钥并生成新密钥。仓库应接入密钥扫描工具。
  • 未限流导致排队:请求堆积会拖慢所有调用方。启用限流,并调整MAX_CONCURRENT。

发表评论

活动