从0到1搭一个云原生大模型推理平台：FastAPI + vLLM + Kubernetes + Prometheus

最近我做了一个小型的云原生大模型推理平台项目主要目的是把大模型服务从“能调用”往“能部署、能治理、能观测”推进一步。项目地址https://github.com/ycx666994/llm-inference-platform这个项目不是简单写一个接口去调用大模型 API而是围绕大模型推理服务搭了一层网关支持 OpenAI 兼容接口、API Key 鉴权、限流、Prometheus 指标、Grafana 监控、Kubernetes 部署和 k6 压测。一我为什么做这个项目刚开始接触大模型应用时很多 Demo 都是直接调用 API比如写个聊天机器人、RAG 问答系统之类的。这些当然很有价值但如果从AI Infra 或平台工程角度看还缺少一个关键问题模型服务真正上线以后怎么部署怎么限流怎么鉴权怎么监控怎么压测怎么迁移到 Kubernetes所以我想做一个更偏底层一点的项目不重点展示“模型回答得多聪明”而是展示一个大模型推理服务背后的工程化能力。二项目整体架构项目的核心结构大概是这样Client / k6|vFastAPI Gateway|-- API Key Auth|-- Rate Limit|-- Prometheus Metrics|vmock-vLLM / real vLLM|vPrometheus Grafana三项目里主要的部分gateway/ FastAPI 推理网关mock-vllm/ OpenAI 兼容的 mock 后端k8s/ Kubernetes 部署文件monitoring/ Prometheus 和 Grafana 配置benchmark/ k6 压测脚本scripts/ 本地和 K8s 部署脚本docs/ 架构说明、运行手册、压测报告四Gateway 的设计Gateway 是这个项目的核心。因为客户端不会直接请求 vLLM而是先请求 Gateway。这样做的好处是很多和模型无关但上线必须要有的能力都可以放在 Gateway 层做比如说1.API Key 鉴权2.请求限流3.请求转发4.默认模型补全5.Prometheus 指标采集6.上游错误处理五接口的设计接口设计上我做成了 OpenAI 兼容格式POST /v1/chat/completions这样客户端侧可以比较自然地迁移不需要重新适配一套奇怪的协议。六健康检查和指标接口分别是GET /healthzGET /metrics七API Key 鉴权鉴权逻辑比较简单通过请求头里的 Bearer Token 判断是否合法Authorization: Bearer sk-demo如果没有带 token返回 401如果 token 不在允许列表里返回 403。这块虽然不复杂但在推理服务里很重要。因为模型推理通常是高成本资源不可能随便暴露一个无鉴权接口给外部访问。八限流设计我的项目里实现了一个内存版的 per-key 限流器。每个API Key都有自己的请求窗口。当前实现适合本地 Demo 和单实例场景。如果要上生产可以继续改成 Redis 版本这样多个 Gateway 副本之间也能共享限流状态。这个地方我没有一开始就上复杂方案因为项目目标是先把完整链路跑通。工程项目里我觉得很重要的一点是先做出可验证的最小闭环再逐步替换关键组件。九mock-vLLM 和 real vLLM我的这个项目支持两种后端模式第一种是 mock 模式。这个模式不需要 GPU适合本地开发、接口测试、Kubernetes 部署验证。第二种是真实 vLLM 模式。我本地用的是 facebook/opt-125m 作为测试模型。由于本地 kind 集群没有暴露 nvidia.com/gpu所以真实 vLLM 是跑在宿主机 Docker 里的Kubernetes 里的 Gateway 再通过 host.docker.internal:8000去访问它。然后这个方案不是最标准的生产架构但很适合本地演示Client - K8s Gateway - host Docker vLLM当然如果我后续有真正的 GPU Kubernetes 节点应该可以直接使用项目里的 k8s/real-vllm 部署文件再把 vLLM 放进集群里运行。十Prometheus 和 Grafana 监控Gateway 暴露了 Prometheus 指标包括请求数、请求延迟、上游请求状态等。比如gateway_requests_totalgateway_request_latency_secondsgateway_upstream_requests_totalPrometheus 负责采集指标Grafana 用来展示 Dashboard。这样做之后我们就可以看到接口是否正常、请求延迟大概是多少、上游 vLLM 是否有错误。我必须强调一句对大模型推理服务来说监控非常关键。因为一次推理请求可能耗时比较长 也可能因为模型加载、显存、网络、并发等原因出现问题。但如果没有指标的话就很难判断问题到底发生在哪里。十一k6 压测项目里也加了 k6 压测脚本然后我是想用它来测试 Gateway 到后端推理服务的整体表现。然后目前 README 里已经记录了两组结果这里的数值不是为了追求多高的性能而是为了证明整个链路可以被压测、可以被量化。大家请注意一个平台项目如果只有“能跑”其实还不够。最好还能说明它在一定压力下表现怎么样。十二单元测试和 CI后面我又补了一些测试主要覆盖1./healthz 健康检查2.缺少 Bearer Token3.API Key 非法4.请求转发到上游5.默认模型补全6.per-key 限流7./metrics 指标暴露本地测试结果6 passed同时项目中也加了 GitHub Actions这样每次 push 或 pull request 都会自动安装依赖并运行测试。主要是我想方便展示给大家。别人打开仓库时能看到项目不是只写了一堆代码而是有基本的工程质量保障。十三本地快速验证如果只想验证 Gateway 的基本行为不需要 Docker、Kubernetes 或 GPU可以直接跑测试cd C:\Users\HP\llm-inference-platformpython -m venv .venv.\.venv\Scripts\Activate.ps1pip install -r gateway\requirements.txt -r requirements-dev.txt$env:PYTHONPATHgatewaypytest -q启动Gateway$env:PYTHONPATHgatewayuvicorn app.main:app --host 127.0.0.1 --port 8080测试健康检查Invoke-RestMethod -Method Get -Uri http://127.0.0.1:8080/healthz查看指标Invoke-WebRequest -Uri http://127.0.0.1:8080/metrics -UseBasicParsing如果要测试完整的 chat completions 转发就需要先启动 mock-vLLM 或真实 vLLM。十四收获我说说我的收获。其实这个项目我最大的收获不是 FastAPI 怎么写也不是 Kubernetes YAML 怎么写而是我对“大模型推理服务工程化”有了更完整的理解。以前看大模型项目更多关注模型本身比如参数量、推理效果、上下文长度。做完这个项目之后会发现真正上线时还有很多模型外的问题1.请求入口怎么统一2.用户怎么鉴权3.不同用户怎么限流4.服务挂了怎么发现5.延迟变高怎么定位6.本地怎么测试7.Kubernetes 里怎么部署8.GPU 不可用时怎么做 fallback 或 mock这些问题单独看都不算特别难但把它们串成一个完整系统就很接近真实平台工程的工作方式。十五总结这个项目可以理解为一个小型的大模型推理平台雏形。它没有追求复杂的业务功能而是把重点放在推理服务的工程化链路上Gateway、鉴权、限流、监控、压测、Kubernetes 部署和CI。如果只是做大模型应用直接调用 API 就够了。但如果想往 AI Infra、云原生、平台工程方向深入就必须理解模型服务背后的这些基础设施能力。这个项目也算是我对这条技术路线的一次实践。后面我会继续完善它因为还有很多的东西需要完善然后我争取把它从 Demo 项目逐步打磨成一个更完整的 LLM Serving Platform。欢迎大家留言以及欢迎大家来开源贡献。