14. 服务、部署与可观测性

14.1 本地开发服务

MLX-LM：

mlx_lm.server \
  --model mlx-community/Qwen3-8B-4bit \
  --host 127.0.0.1 \
  --port 8080

llama.cpp：

llama-server \
  -hf Qwen/Qwen3-8B-GGUF:Q4_K_M \
  -ngl 99 \
  -c 8192 \
  --host 127.0.0.1 \
  --port 8081

这类本地 server 便于学习 OpenAI-compatible API，但不要未经鉴权直接暴露公网。

14.2 生产推理要解决什么

• 模型加载和多副本管理。
• 请求排队、batch 和优先级。
• KV Cache 分配与回收。
• 流式输出和客户端取消。
• 超时、限流、重试和熔断。
• 模型版本、灰度与回滚。
• 提示词和数据隐私。
• GPU/CPU/内存监控。
• 输出安全策略。

14.3 延迟和吞吐的冲突

等待更多请求组 batch：

• 总吞吐可能提高。
• 单个请求排队时间增加。

应按服务等级目标设计：

交互聊天：重视 TTFT 和 TPOT
离线批处理：重视总 token/s 和成本
高并发 API：重视 P50/P95/P99、拒绝率和队列长度

平均值会隐藏长尾，生产环境必须看分位数。

14.4 vLLM

vLLM 提供离线批量推理和 OpenAI-compatible server，其重点包括高效 KV Cache 管理、连续批处理和多 GPU 支持。

当前 vLLM 文档通过独立的 vLLM-Metal 插件提供 Apple Silicon 路线；该插件使用 MLX 作为计算后端，功能和安装约束应以插件文档为准。如果学习目标是 CUDA 数据中心推理，仍需在 Linux + NVIDIA 环境单独练习 tensor parallel、NCCL 和 CUDA 内核。

概念命令：

vllm serve Qwen/Qwen3-0.6B

实际安装和设备参数变化较快，执行前使用本手册末尾的官方 vLLM Quickstart。

14.5 可观测性

最低限度记录：

• 请求数、错误率和取消率。
• TTFT、TPOT、端到端 P50/P95/P99。
• 输入/输出 token 数。
• 当前并发、队列长度、batch 大小。
• KV Cache 使用率。
• 内存、GPU 利用率、功耗。
• 模型、adapter 和 prompt 版本。
• 工具调用成功率。
• 安全拦截与人工升级率。

日志要脱敏。不要把用户隐私、访问令牌或完整机密 prompt 随意写入日志。

14.6 动手：把 TinyGPT 暴露为可测量的本地 API

实验 08｜Local Serving　资源：已完成实验 04；时间：约 5 分钟；产物：健康检查、生成响应、错误响应和延迟记录。

先确保 checkpoint 存在，再启动只监听本机的服务：

python code/09_serve_tiny_gpt.py \
  --checkpoint artifacts/checkpoints/tiny-gpt-base.pt \
  --host 127.0.0.1 \
  --port 8080

另开终端检查健康状态：

curl -fsS http://127.0.0.1:8080/healthz

响应应包含 status=ok 与实际 device。请求生成：

curl -fsS \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"注意力","max_new_tokens":40,"temperature":0.8}' \
  http://127.0.0.1:8080/v1/generate

响应除了文本，还包含 prompt token、生成 token、总耗时和 token/s。随后必须测试错误路径：空请求、词表外 prompt、超大 max_new_tokens 和不存在的路由。

这个教学服务故意没有实现生产能力。进入部署前，需要补齐：

• 请求 schema、鉴权、Workspace 权限与限流。
• 流式输出、客户端取消、超时和背压。
• 有界队列与并发策略，不能让请求无限堆积。
• 模型/Adapter 版本、TTFT、TPOT、错误率和资源指标。
• 结构化、脱敏日志，以及灰度和回滚机制。

验收标准：API 能正常返回并不等于服务完成；还要证明错误输入可诊断、指标口径明确、只监听预期网络接口，并能说明为什么不能直接暴露公网。