1. 为什么我把AI微服务底座当成基础设施来装这两年微服务架构本身已经是老生常谈真正让团队头疼的是AI 微服务这个概念落地的成本。传统微服务无非是用户服务、订单服务、支付服务那一套注册中心、网关、配置中心一拉大家闭着眼都能搭。但一旦涉及 AI事情就变了模型推理要单独做服务化向量检索要接专门的数据库智能体编排可能要引入新的工作流引擎再加上和原来那一套注册发现、网关、监控体系的衔接——你会发现整个底座不再是Spring Boot Nacos Gateway三件套能搞定的了。我见过太多团队卡在这个阶段。有的人最先败在环境上文件里写了依赖 Milvus、要求 GPU 驱动某个版本、模型文件放哪个路径结果不同机器上装出来行为完全不一样。有的人败在参数上向量索引类型选错了召回率差得离谱推理服务的并发数没调好一压测就直接 OOM。这些问题的根源不是某个组件难装而是整个底座涉及的组件太多了手动一步步装很容易在某一环埋下隐患。所以我这次想聊的是向导式安装这个思路。它不是一个新概念数据库、中间件领域早就这么干了但对 AI 微服务底座来说它带来的价值是质的提升把环境检测、组件编排、参数初始化、健康检查全部固化成交互式引导流程让一台裸机上的操作从读文档 2 小时 踩坑 1 天变成点下一步 10 分钟。文章后面我会完整走一遍从零安装到跑通第一个 AI 服务的过程并把我实际用下来的几个关键经验和坑一起写出来。如果你正准备在公司内部搭一套 AI 微服务的公共底座或者想在自己电脑上快速起一个可复现的 AI 服务环境这篇文章应该能帮你省下不少时间。2. 安装前先想清楚底座里到底该装哪几样向导式安装快的前提是它已经把架构选型和组件清单固化好了。但作为使用者你最好还是清楚里面装的是什么否则后面调优、排障会两眼一抹黑。2.1 从传统微服务到 AI 微服务新增了哪些关键角色传统微服务底座的核心三件套是注册中心、配置中心、API 网关。AI 微服务底座在这之上通常会额外加三个角色模型推理服务、向量数据库、智能体/工作流运行时。我整理了一张分工表你可以先对号入座组件角色典型选型核心职责传统微服务里对应物服务注册与发现Nacos / Consul管理所有微服务实例的上下线与负载均衡无变化API 网关Spring Cloud Gateway / Kong统一入口、鉴权、限流、路由分发无变化模型推理服务vLLM / Triton Inference Server把大模型封装成标准 HTTP 接口管理显存和并发对应业务后端服务但生命周期更重向量数据库Milvus / pgvector / Qdrant存储 Embedding 向量支撑语义检索和 RAG对应传统数据库但索引机制完全不同智能体运行时LangChain 服务化 / 自研 Agent 调度编排多步推理、工具调用、记忆管理对应业务流程引擎可观测性Prometheus Grafana Loki指标、日志、链路追踪无变化但 AI 场景额外关注 GPU 指标这样列出来你就能看出来AI 微服务底座并不是把传统微服务推翻重来而是在原有骨架上长了几个新器官。这也意味着安装环节必须同时处理两类依赖一类是注册中心、网关这类老伙计的版本兼容另一类是 GPU 驱动、CUDA、向量库这类新住户的环境要求。2.2 机器规划先算清楚显存、内存和磁盘如果你要部署的是基于大模型的 AI 微服务第一个要算的账是显存。以我最常用的 7B 参数模型为例模型权重文件大约 14GB用 FP16 加载进显存至少需要模型大小 参数量(70亿) × 2字节(FP16) ≈ 14GB 推理时开销 14GB × 1.2 ≈ 16.8GB KV Cache 预留 并发数(4) × 每请求预留(约1GB) ≈ 4GB 最低显存需求 ≈ 21GB如果你只有一张 24GB 显存的消费级显卡跑 7B 模型加 4 并发是勉强够的但不建议把上下文长度拉太长。如果模型换成 13BFP16 权重就要 26GB那就必须换 32GB 以上显存的卡或者用 AWQ/GPTQ 量化到 4bit把模型体积压到 7GB 左右。内存方面向量数据库是个容易被低估的角色。Milvus 在用 HNSW 索引的时候会把一部分图结构驻留在内存里通用经验是每 100 万条 768 维的向量HNSW 索引大概占用 2~3GB 内存。如果你打算存 1000 万条光索引就要吃掉 20~30GB这个量级必须在上机器之前算清楚否则装到一半内存不够安装向导也救不了你。磁盘反而是最好解决的模型文件、向量数据、日志三块分离即可。模型目录和建议给 50GB 以上的空闲空间因为后续换更大的模型文件是常态。2.3 端口规划和网络策略向导式安装到最后一步通常会做端口冲突检测但不同机器上装了什么你是最清楚的。我建议你提前把这一套端口固定下来后续写防火墙白名单、网关路由、监控采集都用得着端口用途8848Nacos 注册中心与配置中心8080Spring Cloud Gateway 网关入口8000vLLM 模型推理服务19530Milvus 向量数据库 gRPC9090Prometheus 指标端点3000Grafana 可视化面板这里的核心思路是网关收流量组件不入网。所有外部请求只打到 8080内部服务之间通过 Nacos 的服务名互相发现不暴露每台机器的具体端口。这样做的好处是AI 微服务底座里某个组件的端口变了你只需要在对应的注册配置里改网关和外部调用方完全不受影响。3. 向导式安装实录从下载安装器到第一个服务注册成功前面铺垫了这么多现在进入正题。我用一套基于 Spring Boot 3 Nacos Spring Cloud Gateway vLLM Milvus 的开源 AI 微服务底座做演示它的安装器提供 Web 形式的向导界面。整个过程分六个阶段跟着走完大概 10~12 分钟。3.1 环境检测阶段向导替你扫雷的第一步下载好安装包后解压目录里会有一个installer可执行文件。运行它浏览器会自动打开http://localhost:9002进入向导首页。第一次打开会看到一个环境自检报告项目会去探测当前机器上的关键依赖。我那次跑出来的结果大概是这样的[√] Docker 版本 24.0.7 [√] Docker Compose 版本 v2.21.0 [√] 可用内存 31.2GB [√] 可用磁盘 200GB [√] NVIDIA 驱动版本 550.54.14 [√] NVIDIA Container Toolkit 已安装 [!] 显存 23.1GB / 建议至少 24GB看到那个惊叹号我当时心里紧了一下。后来查了一下这个提示是按 8B 模型 8 并发去算的最低推荐值我的卡 23.1GB 跑 4 并发是够用的所以点击继续即可。这一步对新手特别友好以前我自己手动配环境经常是 Docker 装了但 Compose 插件没装驱动版本太老导致容器里nvidia-smi都跑不出来。向导在这里一次性检查完毕相当于把最容易出问题的环境雷区提前排掉了。如果你在自检阶段看到某个依赖标记为[!]甚至[x]不要盲目跳过。我建议你按照向导页面的提示链接去补齐对应软件然后再点一次重新检测。很多环境问题如果在这里被忽略会在后面部署阶段以更诡异的形式冒出来反而更浪费时间。3.2 组件选择阶段按需勾选但拒绝了全选环境检测通过后进入组件选择页。我把这个页面的选项列一下方便你对号入座基础微服务底座Nacos、Gateway、服务管理后台模型推理服务vLLM默认开启 GPU 模式向量知识库Milvus含 Attu 管理界面可观测性套件Prometheus、Grafana、Loki智能体编排示例服务基于 LangChain 的 Agent 示例大多数人看到这么多组件的第一反应是全选。但我建议你在这个页面稍微克制一下如果你当前只需要把模型服务跑起来做接口联调智能体编排示例服务可以先不选它能省下差不多 2 分钟部署时间和不少内存。我第一次装的时候是全选的结果笔记本电脑风扇直接起飞。后来在正式环境里我做了拆分把智能体编排拆到单独的部署单元避免和推理服务抢显存。这个页面还有一个细节值得说每个组件前面有一个小的信息按钮鼠标悬停会显示推荐配置。比如 Milvus 那一条写着建议内存不低于 8GB向量数据量低于 100 万条时可使用默认配置。这些信息不是随便写的它是安装器对不同组件资源配额的估算依据建议你至少在悬停提示显示当前配置偏低时多留意一眼。3.3 参数配置与初始化密码、路径、模型唯一标识组件选完后进入参数配置页。这里的每个输入框都对应后续生成的配置文件里的具体字段所以我会逐个看过去不直接点默认。最重要的三个配置项我单独拿出来讲。第一个是统一管理员密码它会被用于 Nacos 控制台、Grafana 面板和服务管理后台。安装器会做强度校验要求至少 8 位且包含大小写字母和数字。第二个是数据目录也就是所有组件的持久化数据存放位置。默认是~/ai-stack-data我建议改成独立数据盘避免和系统盘放在一起。第三个是模型标识这是给 vLLM 用的模型名称例如qwen2-7b-instruct。安装器会根据这个标识生成模型服务的访问路径和健康检查命令。这一步让人容易犯的错误是把模型标识写成了文件路径。注意这里填的不是模型文件的绝对路径而是模型在推理服务里的逻辑名称。模型文件的路径在后续模型配置阶段单独设置。分开设计是有道理的——逻辑名称是稳定不变的物理路径可以随时调整不需要改动网关路由。配置完成后点击下一步安装器会把这些参数渲染成一份完整的部署清单包括每个组件的 Docker 启动参数、环境变量、挂载路径。你可以在提交前最后一页检查一遍部署清单确认端口没有冲突、数据目录路径正确然后点开始部署。3.4 部署与进度可视化等待不再是黑箱部署阶段是整个安装过程中最让人安心的一步因为所有进度都在页面上可视化展示。我那次安装整个进度大概分为这几个阶段[1/6] 拉取基础镜像 (nacos, gateway) [2/6] 启动 Nacos 注册中心并等待健康 [3/6] 启动 Milvus 向量数据库及依赖组件 [4/6] 启动 vLLM 模型推理服务 [5/6] 初始化网关路由与配置中心数据 [6/6] 启动可观测性组件并执行全链路健康检查页面右下角有查看实时日志的入口点开之后可以看到每个容器的启动输出。有一次我在部署到第 4 步时卡了大概 3 分钟日志显示CUDA out of memory原因是同一台机器上有另一个程序占用了约 6GB 显存。这时候我先把那个程序停掉点击页面的重试当前步骤后续就顺利了。这个设计比整体重来好很多——它允许你单独修复某一个组件的失败而不是让整批容器全部销毁重建。所有步骤都跑完后页面会显示部署完成然后直接给你一张访问信息汇总表包含各个控制台的地址、初始账号、以及一个探测命令往网关发一个带服务名的请求确认服务是否成功注册。整个过程从下载安装器到看到这张表我实测大约 11 分钟中间没有翻过任何文档。4. 装完别急着高兴验证底座健康的五个关键检查向导式安装器在最后一步会做健康检查但它检查的是服务进程活着不是服务真的能用。我习惯在安装完成后手动跑一遍业务链路的验证确保中间任何一层的问题都能第一时间暴露出来。4.1 网关路由测试与 Nacos 服务列表核对第一步是确认 Nacos 上的服务注册情况和网关转发规则是否匹配。打开 Nacos 控制台端口 8848左侧服务管理-服务列表里你应该能看到至少四个服务gateway-server、model-service、vector-service、admin-service。每个服务的实例数应该和部署时勾选的组件数一致。然后针对网关做一次最小验证。在安装完成页给出的服务探测命令用的就是这样的思路curl -X GET http://localhost:8080/actuator/health这个请求会经过网关由网关转发到注册中心的健康检查端点。如果返回{status:UP}说明网关和注册中心这条链路是通的。如果超时优先去查网关容器的日志看是不是路由配置里的服务名和 Nacos 里的服务名不一致——这是我在多个环境里遇到过的最高频问题。4.2 模型推理服务端到端验证带真实请求跑一遍接下来是 AI 底座的核心——模型推理服务。vLLM 启动后模型接口默认在http://localhost:8000/v1/chat/completions。我会发一个非常短的请求验证它curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2-7b-instruct, messages: [{role: user, content: 你好请回答112 是否正确}], max_tokens: 16 }注意model字段的值必须和安装时填写的模型标识完全一致否则 vLLM 会返回 404。返回正常时会带上usage字段里面有prompt_tokens和completion_tokens这个数据可以留作后续压测的基线。如果你在安装时输入的是一个还不存在的模型标识或者模型文件路径不对vLLM 启动阶段就会报错这个请求自然不通。遇到这种情况优先去检查模型存储目录的文件是否完整因为大模型文件经常出现下载到一半断掉的情况。4.3 向量数据库写入与召回验证向量数据库是 AI 微服务里最容易被跳过测试的组件因为很多人一时不知道往里面写什么。我的做法是通过工具箱里的 Attu 管理界面默认 9004 端口直接执行一个简单操作创建测试 collection写入 3 条随机向量再执行一次精确搜索。如果写入和搜索都能成功说明 Milvus 的 19530 端口通信正常索引分区也能响应。这里要特别强调一个理解误区向量数据库能不能用的标准不是控制台能打开而是写入的向量能被准确地搜出来。因为 Milvus 底层涉及文件分片、索引构建和对象存储通常是 MinIO的联动任何一个环节配置错误写入时可能不报错但搜索时结果为空。安装完成后当天把这条链路跑通每天增量写入数据时才不会遇到突然查不出来的事故。4.4 显存、GPU 利用率与监控面板核查AI 底座和传统微服务最大的观测差异在 GPU 指标。安装好的 Prometheus Grafana 里如果配置正确应该能看到 NVIDIA 显卡的显存使用率、GPU 利用率、温度这几个面板。我一般会有一个简单的判据空载时显存占用 模型权重占用 约 1GB 缓存GPU 利用率应低于 5% 推理时GPU 利用率应冲到 60% 以上显存占用在预设的 max_model_len 内波动如果空载时 GPU 利用率就已经很高多半是有人在占资源或者推理服务的gpu_memory_utilization参数设得过高。vLLM 默认会吃掉显存的 90%如果你的机器还要跑其他 GPU 程序建议启动参数里把这个值调到0.6~0.7。这个参数直接影响你能同时跑几个模型服务属于安装完成后必须复查的配置项。4.5 清理安装器进程与锁定版本基线最后一个步骤往往被人忽略把向导安装器的进程停掉并把安装时生成的版本清单保存下来。安装完成页有一个导出部署清单的按钮点击后能得到一份 YAML 文件记录着每个组件的镜像版本、启动参数、数据目录。这份文件就是整个 AI 底座当前环境的指纹后续升级组件或者迁移机器时它是最可靠的参照物。我这里也把验证过程中最常用的命令汇总成一个快捷清单方便你复制使用# 查看所有组件容器状态 docker compose -f ai-stack/docker-compose.yaml ps # 查看 Nacos 服务注册状态通过管理端 API curl -X GET http://localhost:8848/nacos/v1/ns/operator/metrics # 查看 vLLM 推理服务健康状态 curl -X GET http://localhost:8000/health # 查看 Milvus 健康状态 curl -X GET http://localhost:9091/healthz # 实时查看推理服务日志 docker logs -f $(docker ps | grep vllm | awk {print $1})5. 跑通了只是开始这几个月里我踩过的坑与调优记录如果你的目标只是本地起一个 demo看到这里就可以去动手装了。但如果你想把 AI 微服务底座真正用于测试环境甚至准生产环境下面这些基于实际使用经验的调整大概率能帮你少走很多弯路。5.1 推理服务的并发世界不是模型大吞吐就高我第一次压测时犯了一个典型错误把并发数从 1 直接调到 16然后满怀期待地看吞吐曲线结果每秒请求数反而下降了还伴随大量超时。后来我搞清楚了vLLM 的批处理机制和传统 Web 服务完全不同。它不是简单地一个请求分配一个线程而是在一个推理引擎内部做 continuous batching——多个请求共享一次前向传播。并发数设太高每个请求的 KV Cache 都要占显存显存不够了反而触发切换和排队。实际的调参经验是从并发数 1 开始逐步加压同时观察 GPU 利用率和首 token 延迟。找到一个拐点也就是 GPU 利用率接近饱和、但显存还没到红线的那个点。我目前用的 7B 模型在单卡 24GB 环境下稳定并发大概在 8 左右超过 8 之后收益就不明显了。你可以直接通过修改模型服务的环境变量--max-num-seqs来调整这个值改完之后重启容器即可生效。5.2 向量索引参数HNSW 的 M 和 efConstructionMilvus 默认创建的索引类型是 HNSW它有两个关键参数M每个节点的最大连接数和efConstruction构建时动态列表大小。默认参数M16, efConstruction200在 100 万条向量以内表现良好但如果数据量上来这个组合会产生两个问题检索变慢、内存占用变大。我的建议是分阶段调整。数据量在 100 万条以下保持默认即可超过 100 万条把M从 16 调到 32efConstruction保持在 200召回率会有明显提升但构建索引的时间也会翻倍。这里要提醒的是M值的最佳范围是 16~64太大会导致图结构过于密集检索路径反而变长efConstruction太高会让索引构建阶段成为整个链路的新瓶颈。5.3 日志与链路追踪AI 场景必须单独记录 tokens传统微服务的链路追踪只管这次请求花了多少毫秒调用了哪些服务。到了 AI 场景链路追踪里缺了 token 数据就等于没有真正观测到业务。我后来在网关层加了一个自定义过滤器把每次推理请求的prompt_tokens、completion_tokens、模型名称、请求来源这四元组写入 Loki单独组成了一个叫ai_model_usage的日志流。这样做带来的直接收益是成本可审计。即使现在模型是私有化部署token 数也直接对应算力消耗和响应时间。后续如果要给不同业务线分配资源配额或者在接口层面控制某个调用方的用量上限这条自定义链路就是数据基础。具体的实现在 Spring Cloud Gateway 里不算复杂就是在 WebFilter 里解析响应体把 vLLM 返回的usage字段摘出来异步写入消息队列再由 Logstash 或者 Promtail 采集。5.4 多环境隔离与升级节奏底座跑稳之后第二个问题就是怎么管理多个环境。我不会在同一个 Nacos 命名空间里混跑测试和正式环境而是利用 Nacos 的多命名空间能力把dev、staging、prod三套环境彻底隔开。切换环境时网关和数据源配置都跟着 namespace 走模型文件路径也可以区分开比如测试环境用量化版小模型正式环境用全精度模型。升级节奏方面我个人的实践准则是网关、注册中心、配置中心这些小升级跟着季度版本走模型推理框架 vLLM 和向量数据库属于 AI 底座的核心如果当前版本没有明显 bug不要轻易追新版本。尤其 vLLM 的版本和 CUDA、PyTorch 的兼容性强耦合盲升一个 minor 版本可能换来的是整套推理链路不稳定。每次升级我都会先在 staging 环境跑一轮 4.2 到 4.4 的全链路验证确认指标没恶化再上生产。5.5 日常巡检脚本的雏形最后分享一个实用习惯。向导式安装把整个底座搭起来之后我不靠人肉检查状态而是写了一个简单的巡检脚本每天早上自动跑一遍前文提到的关键检查项。脚本逻辑很简单# 检查 Nacos 服务列表 curl -s http://localhost:8848/nacos/v1/ns/catalog/services?pageNo1pageSize10 | grep -c model-service # 检查 vLLM 推理服务健康 curl -s -o /dev/null -w %{http_code} http://localhost:8000/health # 检查 GPU 显存余量 nvidia-smi --query-gpumemory.used,memory.total --formatcsv # 检查 Milvus 状态 curl -s http://localhost:9091/healthz把结果写入一个文件再配合一个简单的告警规则——比如vLLM 健康检查连续三次失败或显存使用率超过 95%才会触发告警。这套机制运行下来绝大多数问题都能在用户感知之前被捕获也让10 分钟装起来的底座真正具备了长期稳定运行的基础。总的来说向导式安装解决的是从零到一的效率问题而接下来的稳定性工作靠的还是对每一个关键组件的理解和对业务节奏的把握。希望我这次从装到用的完整记录能让你在搭自己的 AI 微服务底座时少踩几个我已经替你踩过的坑。 AI微服务底座向导式安装全指南：从环境检测到跑通推理服务
1. 为什么我把AI微服务底座当成基础设施来装这两年微服务架构本身已经是老生常谈真正让团队头疼的是AI 微服务这个概念落地的成本。传统微服务无非是用户服务、订单服务、支付服务那一套注册中心、网关、配置中心一拉大家闭着眼都能搭。但一旦涉及 AI事情就变了模型推理要单独做服务化向量检索要接专门的数据库智能体编排可能要引入新的工作流引擎再加上和原来那一套注册发现、网关、监控体系的衔接——你会发现整个底座不再是Spring Boot Nacos Gateway三件套能搞定的了。我见过太多团队卡在这个阶段。有的人最先败在环境上文件里写了依赖 Milvus、要求 GPU 驱动某个版本、模型文件放哪个路径结果不同机器上装出来行为完全不一样。有的人败在参数上向量索引类型选错了召回率差得离谱推理服务的并发数没调好一压测就直接 OOM。这些问题的根源不是某个组件难装而是整个底座涉及的组件太多了手动一步步装很容易在某一环埋下隐患。所以我这次想聊的是向导式安装这个思路。它不是一个新概念数据库、中间件领域早就这么干了但对 AI 微服务底座来说它带来的价值是质的提升把环境检测、组件编排、参数初始化、健康检查全部固化成交互式引导流程让一台裸机上的操作从读文档 2 小时 踩坑 1 天变成点下一步 10 分钟。文章后面我会完整走一遍从零安装到跑通第一个 AI 服务的过程并把我实际用下来的几个关键经验和坑一起写出来。如果你正准备在公司内部搭一套 AI 微服务的公共底座或者想在自己电脑上快速起一个可复现的 AI 服务环境这篇文章应该能帮你省下不少时间。2. 安装前先想清楚底座里到底该装哪几样向导式安装快的前提是它已经把架构选型和组件清单固化好了。但作为使用者你最好还是清楚里面装的是什么否则后面调优、排障会两眼一抹黑。2.1 从传统微服务到 AI 微服务新增了哪些关键角色传统微服务底座的核心三件套是注册中心、配置中心、API 网关。AI 微服务底座在这之上通常会额外加三个角色模型推理服务、向量数据库、智能体/工作流运行时。我整理了一张分工表你可以先对号入座组件角色典型选型核心职责传统微服务里对应物服务注册与发现Nacos / Consul管理所有微服务实例的上下线与负载均衡无变化API 网关Spring Cloud Gateway / Kong统一入口、鉴权、限流、路由分发无变化模型推理服务vLLM / Triton Inference Server把大模型封装成标准 HTTP 接口管理显存和并发对应业务后端服务但生命周期更重向量数据库Milvus / pgvector / Qdrant存储 Embedding 向量支撑语义检索和 RAG对应传统数据库但索引机制完全不同智能体运行时LangChain 服务化 / 自研 Agent 调度编排多步推理、工具调用、记忆管理对应业务流程引擎可观测性Prometheus Grafana Loki指标、日志、链路追踪无变化但 AI 场景额外关注 GPU 指标这样列出来你就能看出来AI 微服务底座并不是把传统微服务推翻重来而是在原有骨架上长了几个新器官。这也意味着安装环节必须同时处理两类依赖一类是注册中心、网关这类老伙计的版本兼容另一类是 GPU 驱动、CUDA、向量库这类新住户的环境要求。2.2 机器规划先算清楚显存、内存和磁盘如果你要部署的是基于大模型的 AI 微服务第一个要算的账是显存。以我最常用的 7B 参数模型为例模型权重文件大约 14GB用 FP16 加载进显存至少需要模型大小 参数量(70亿) × 2字节(FP16) ≈ 14GB 推理时开销 14GB × 1.2 ≈ 16.8GB KV Cache 预留 并发数(4) × 每请求预留(约1GB) ≈ 4GB 最低显存需求 ≈ 21GB如果你只有一张 24GB 显存的消费级显卡跑 7B 模型加 4 并发是勉强够的但不建议把上下文长度拉太长。如果模型换成 13BFP16 权重就要 26GB那就必须换 32GB 以上显存的卡或者用 AWQ/GPTQ 量化到 4bit把模型体积压到 7GB 左右。内存方面向量数据库是个容易被低估的角色。Milvus 在用 HNSW 索引的时候会把一部分图结构驻留在内存里通用经验是每 100 万条 768 维的向量HNSW 索引大概占用 2~3GB 内存。如果你打算存 1000 万条光索引就要吃掉 20~30GB这个量级必须在上机器之前算清楚否则装到一半内存不够安装向导也救不了你。磁盘反而是最好解决的模型文件、向量数据、日志三块分离即可。模型目录和建议给 50GB 以上的空闲空间因为后续换更大的模型文件是常态。2.3 端口规划和网络策略向导式安装到最后一步通常会做端口冲突检测但不同机器上装了什么你是最清楚的。我建议你提前把这一套端口固定下来后续写防火墙白名单、网关路由、监控采集都用得着端口用途8848Nacos 注册中心与配置中心8080Spring Cloud Gateway 网关入口8000vLLM 模型推理服务19530Milvus 向量数据库 gRPC9090Prometheus 指标端点3000Grafana 可视化面板这里的核心思路是网关收流量组件不入网。所有外部请求只打到 8080内部服务之间通过 Nacos 的服务名互相发现不暴露每台机器的具体端口。这样做的好处是AI 微服务底座里某个组件的端口变了你只需要在对应的注册配置里改网关和外部调用方完全不受影响。3. 向导式安装实录从下载安装器到第一个服务注册成功前面铺垫了这么多现在进入正题。我用一套基于 Spring Boot 3 Nacos Spring Cloud Gateway vLLM Milvus 的开源 AI 微服务底座做演示它的安装器提供 Web 形式的向导界面。整个过程分六个阶段跟着走完大概 10~12 分钟。3.1 环境检测阶段向导替你扫雷的第一步下载好安装包后解压目录里会有一个installer可执行文件。运行它浏览器会自动打开http://localhost:9002进入向导首页。第一次打开会看到一个环境自检报告项目会去探测当前机器上的关键依赖。我那次跑出来的结果大概是这样的[√] Docker 版本 24.0.7 [√] Docker Compose 版本 v2.21.0 [√] 可用内存 31.2GB [√] 可用磁盘 200GB [√] NVIDIA 驱动版本 550.54.14 [√] NVIDIA Container Toolkit 已安装 [!] 显存 23.1GB / 建议至少 24GB看到那个惊叹号我当时心里紧了一下。后来查了一下这个提示是按 8B 模型 8 并发去算的最低推荐值我的卡 23.1GB 跑 4 并发是够用的所以点击继续即可。这一步对新手特别友好以前我自己手动配环境经常是 Docker 装了但 Compose 插件没装驱动版本太老导致容器里nvidia-smi都跑不出来。向导在这里一次性检查完毕相当于把最容易出问题的环境雷区提前排掉了。如果你在自检阶段看到某个依赖标记为[!]甚至[x]不要盲目跳过。我建议你按照向导页面的提示链接去补齐对应软件然后再点一次重新检测。很多环境问题如果在这里被忽略会在后面部署阶段以更诡异的形式冒出来反而更浪费时间。3.2 组件选择阶段按需勾选但拒绝了全选环境检测通过后进入组件选择页。我把这个页面的选项列一下方便你对号入座基础微服务底座Nacos、Gateway、服务管理后台模型推理服务vLLM默认开启 GPU 模式向量知识库Milvus含 Attu 管理界面可观测性套件Prometheus、Grafana、Loki智能体编排示例服务基于 LangChain 的 Agent 示例大多数人看到这么多组件的第一反应是全选。但我建议你在这个页面稍微克制一下如果你当前只需要把模型服务跑起来做接口联调智能体编排示例服务可以先不选它能省下差不多 2 分钟部署时间和不少内存。我第一次装的时候是全选的结果笔记本电脑风扇直接起飞。后来在正式环境里我做了拆分把智能体编排拆到单独的部署单元避免和推理服务抢显存。这个页面还有一个细节值得说每个组件前面有一个小的信息按钮鼠标悬停会显示推荐配置。比如 Milvus 那一条写着建议内存不低于 8GB向量数据量低于 100 万条时可使用默认配置。这些信息不是随便写的它是安装器对不同组件资源配额的估算依据建议你至少在悬停提示显示当前配置偏低时多留意一眼。3.3 参数配置与初始化密码、路径、模型唯一标识组件选完后进入参数配置页。这里的每个输入框都对应后续生成的配置文件里的具体字段所以我会逐个看过去不直接点默认。最重要的三个配置项我单独拿出来讲。第一个是统一管理员密码它会被用于 Nacos 控制台、Grafana 面板和服务管理后台。安装器会做强度校验要求至少 8 位且包含大小写字母和数字。第二个是数据目录也就是所有组件的持久化数据存放位置。默认是~/ai-stack-data我建议改成独立数据盘避免和系统盘放在一起。第三个是模型标识这是给 vLLM 用的模型名称例如qwen2-7b-instruct。安装器会根据这个标识生成模型服务的访问路径和健康检查命令。这一步让人容易犯的错误是把模型标识写成了文件路径。注意这里填的不是模型文件的绝对路径而是模型在推理服务里的逻辑名称。模型文件的路径在后续模型配置阶段单独设置。分开设计是有道理的——逻辑名称是稳定不变的物理路径可以随时调整不需要改动网关路由。配置完成后点击下一步安装器会把这些参数渲染成一份完整的部署清单包括每个组件的 Docker 启动参数、环境变量、挂载路径。你可以在提交前最后一页检查一遍部署清单确认端口没有冲突、数据目录路径正确然后点开始部署。3.4 部署与进度可视化等待不再是黑箱部署阶段是整个安装过程中最让人安心的一步因为所有进度都在页面上可视化展示。我那次安装整个进度大概分为这几个阶段[1/6] 拉取基础镜像 (nacos, gateway) [2/6] 启动 Nacos 注册中心并等待健康 [3/6] 启动 Milvus 向量数据库及依赖组件 [4/6] 启动 vLLM 模型推理服务 [5/6] 初始化网关路由与配置中心数据 [6/6] 启动可观测性组件并执行全链路健康检查页面右下角有查看实时日志的入口点开之后可以看到每个容器的启动输出。有一次我在部署到第 4 步时卡了大概 3 分钟日志显示CUDA out of memory原因是同一台机器上有另一个程序占用了约 6GB 显存。这时候我先把那个程序停掉点击页面的重试当前步骤后续就顺利了。这个设计比整体重来好很多——它允许你单独修复某一个组件的失败而不是让整批容器全部销毁重建。所有步骤都跑完后页面会显示部署完成然后直接给你一张访问信息汇总表包含各个控制台的地址、初始账号、以及一个探测命令往网关发一个带服务名的请求确认服务是否成功注册。整个过程从下载安装器到看到这张表我实测大约 11 分钟中间没有翻过任何文档。4. 装完别急着高兴验证底座健康的五个关键检查向导式安装器在最后一步会做健康检查但它检查的是服务进程活着不是服务真的能用。我习惯在安装完成后手动跑一遍业务链路的验证确保中间任何一层的问题都能第一时间暴露出来。4.1 网关路由测试与 Nacos 服务列表核对第一步是确认 Nacos 上的服务注册情况和网关转发规则是否匹配。打开 Nacos 控制台端口 8848左侧服务管理-服务列表里你应该能看到至少四个服务gateway-server、model-service、vector-service、admin-service。每个服务的实例数应该和部署时勾选的组件数一致。然后针对网关做一次最小验证。在安装完成页给出的服务探测命令用的就是这样的思路curl -X GET http://localhost:8080/actuator/health这个请求会经过网关由网关转发到注册中心的健康检查端点。如果返回{status:UP}说明网关和注册中心这条链路是通的。如果超时优先去查网关容器的日志看是不是路由配置里的服务名和 Nacos 里的服务名不一致——这是我在多个环境里遇到过的最高频问题。4.2 模型推理服务端到端验证带真实请求跑一遍接下来是 AI 底座的核心——模型推理服务。vLLM 启动后模型接口默认在http://localhost:8000/v1/chat/completions。我会发一个非常短的请求验证它curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2-7b-instruct, messages: [{role: user, content: 你好请回答112 是否正确}], max_tokens: 16 }注意model字段的值必须和安装时填写的模型标识完全一致否则 vLLM 会返回 404。返回正常时会带上usage字段里面有prompt_tokens和completion_tokens这个数据可以留作后续压测的基线。如果你在安装时输入的是一个还不存在的模型标识或者模型文件路径不对vLLM 启动阶段就会报错这个请求自然不通。遇到这种情况优先去检查模型存储目录的文件是否完整因为大模型文件经常出现下载到一半断掉的情况。4.3 向量数据库写入与召回验证向量数据库是 AI 微服务里最容易被跳过测试的组件因为很多人一时不知道往里面写什么。我的做法是通过工具箱里的 Attu 管理界面默认 9004 端口直接执行一个简单操作创建测试 collection写入 3 条随机向量再执行一次精确搜索。如果写入和搜索都能成功说明 Milvus 的 19530 端口通信正常索引分区也能响应。这里要特别强调一个理解误区向量数据库能不能用的标准不是控制台能打开而是写入的向量能被准确地搜出来。因为 Milvus 底层涉及文件分片、索引构建和对象存储通常是 MinIO的联动任何一个环节配置错误写入时可能不报错但搜索时结果为空。安装完成后当天把这条链路跑通每天增量写入数据时才不会遇到突然查不出来的事故。4.4 显存、GPU 利用率与监控面板核查AI 底座和传统微服务最大的观测差异在 GPU 指标。安装好的 Prometheus Grafana 里如果配置正确应该能看到 NVIDIA 显卡的显存使用率、GPU 利用率、温度这几个面板。我一般会有一个简单的判据空载时显存占用 模型权重占用 约 1GB 缓存GPU 利用率应低于 5% 推理时GPU 利用率应冲到 60% 以上显存占用在预设的 max_model_len 内波动如果空载时 GPU 利用率就已经很高多半是有人在占资源或者推理服务的gpu_memory_utilization参数设得过高。vLLM 默认会吃掉显存的 90%如果你的机器还要跑其他 GPU 程序建议启动参数里把这个值调到0.6~0.7。这个参数直接影响你能同时跑几个模型服务属于安装完成后必须复查的配置项。4.5 清理安装器进程与锁定版本基线最后一个步骤往往被人忽略把向导安装器的进程停掉并把安装时生成的版本清单保存下来。安装完成页有一个导出部署清单的按钮点击后能得到一份 YAML 文件记录着每个组件的镜像版本、启动参数、数据目录。这份文件就是整个 AI 底座当前环境的指纹后续升级组件或者迁移机器时它是最可靠的参照物。我这里也把验证过程中最常用的命令汇总成一个快捷清单方便你复制使用# 查看所有组件容器状态 docker compose -f ai-stack/docker-compose.yaml ps # 查看 Nacos 服务注册状态通过管理端 API curl -X GET http://localhost:8848/nacos/v1/ns/operator/metrics # 查看 vLLM 推理服务健康状态 curl -X GET http://localhost:8000/health # 查看 Milvus 健康状态 curl -X GET http://localhost:9091/healthz # 实时查看推理服务日志 docker logs -f $(docker ps | grep vllm | awk {print $1})5. 跑通了只是开始这几个月里我踩过的坑与调优记录如果你的目标只是本地起一个 demo看到这里就可以去动手装了。但如果你想把 AI 微服务底座真正用于测试环境甚至准生产环境下面这些基于实际使用经验的调整大概率能帮你少走很多弯路。5.1 推理服务的并发世界不是模型大吞吐就高我第一次压测时犯了一个典型错误把并发数从 1 直接调到 16然后满怀期待地看吞吐曲线结果每秒请求数反而下降了还伴随大量超时。后来我搞清楚了vLLM 的批处理机制和传统 Web 服务完全不同。它不是简单地一个请求分配一个线程而是在一个推理引擎内部做 continuous batching——多个请求共享一次前向传播。并发数设太高每个请求的 KV Cache 都要占显存显存不够了反而触发切换和排队。实际的调参经验是从并发数 1 开始逐步加压同时观察 GPU 利用率和首 token 延迟。找到一个拐点也就是 GPU 利用率接近饱和、但显存还没到红线的那个点。我目前用的 7B 模型在单卡 24GB 环境下稳定并发大概在 8 左右超过 8 之后收益就不明显了。你可以直接通过修改模型服务的环境变量--max-num-seqs来调整这个值改完之后重启容器即可生效。5.2 向量索引参数HNSW 的 M 和 efConstructionMilvus 默认创建的索引类型是 HNSW它有两个关键参数M每个节点的最大连接数和efConstruction构建时动态列表大小。默认参数M16, efConstruction200在 100 万条向量以内表现良好但如果数据量上来这个组合会产生两个问题检索变慢、内存占用变大。我的建议是分阶段调整。数据量在 100 万条以下保持默认即可超过 100 万条把M从 16 调到 32efConstruction保持在 200召回率会有明显提升但构建索引的时间也会翻倍。这里要提醒的是M值的最佳范围是 16~64太大会导致图结构过于密集检索路径反而变长efConstruction太高会让索引构建阶段成为整个链路的新瓶颈。5.3 日志与链路追踪AI 场景必须单独记录 tokens传统微服务的链路追踪只管这次请求花了多少毫秒调用了哪些服务。到了 AI 场景链路追踪里缺了 token 数据就等于没有真正观测到业务。我后来在网关层加了一个自定义过滤器把每次推理请求的prompt_tokens、completion_tokens、模型名称、请求来源这四元组写入 Loki单独组成了一个叫ai_model_usage的日志流。这样做带来的直接收益是成本可审计。即使现在模型是私有化部署token 数也直接对应算力消耗和响应时间。后续如果要给不同业务线分配资源配额或者在接口层面控制某个调用方的用量上限这条自定义链路就是数据基础。具体的实现在 Spring Cloud Gateway 里不算复杂就是在 WebFilter 里解析响应体把 vLLM 返回的usage字段摘出来异步写入消息队列再由 Logstash 或者 Promtail 采集。5.4 多环境隔离与升级节奏底座跑稳之后第二个问题就是怎么管理多个环境。我不会在同一个 Nacos 命名空间里混跑测试和正式环境而是利用 Nacos 的多命名空间能力把dev、staging、prod三套环境彻底隔开。切换环境时网关和数据源配置都跟着 namespace 走模型文件路径也可以区分开比如测试环境用量化版小模型正式环境用全精度模型。升级节奏方面我个人的实践准则是网关、注册中心、配置中心这些小升级跟着季度版本走模型推理框架 vLLM 和向量数据库属于 AI 底座的核心如果当前版本没有明显 bug不要轻易追新版本。尤其 vLLM 的版本和 CUDA、PyTorch 的兼容性强耦合盲升一个 minor 版本可能换来的是整套推理链路不稳定。每次升级我都会先在 staging 环境跑一轮 4.2 到 4.4 的全链路验证确认指标没恶化再上生产。5.5 日常巡检脚本的雏形最后分享一个实用习惯。向导式安装把整个底座搭起来之后我不靠人肉检查状态而是写了一个简单的巡检脚本每天早上自动跑一遍前文提到的关键检查项。脚本逻辑很简单# 检查 Nacos 服务列表 curl -s http://localhost:8848/nacos/v1/ns/catalog/services?pageNo1pageSize10 | grep -c model-service # 检查 vLLM 推理服务健康 curl -s -o /dev/null -w %{http_code} http://localhost:8000/health # 检查 GPU 显存余量 nvidia-smi --query-gpumemory.used,memory.total --formatcsv # 检查 Milvus 状态 curl -s http://localhost:9091/healthz把结果写入一个文件再配合一个简单的告警规则——比如vLLM 健康检查连续三次失败或显存使用率超过 95%才会触发告警。这套机制运行下来绝大多数问题都能在用户感知之前被捕获也让10 分钟装起来的底座真正具备了长期稳定运行的基础。总的来说向导式安装解决的是从零到一的效率问题而接下来的稳定性工作靠的还是对每一个关键组件的理解和对业务节奏的把握。希望我这次从装到用的完整记录能让你在搭自己的 AI 微服务底座时少踩几个我已经替你踩过的坑。