我一直觉得AI 应用开发里最劝退人的环节不是写代码而是搭环境。你想做一个带知识库问答的智能体背后要跑模型推理、向量检索、应用编排再来个 API 网关做统一入口这一整套微服务底座手动配下来光依赖冲突和版本不兼容就能耗掉一整个下午。所以我一直琢磨能不能把这套底座做成向导式安装让一个零基础的人跟着界面点几下10 分钟就能从裸机跑起一套能用的 AI 微服务底座。这篇文章要聊的就是我用向导式安装思路落地的一套 AI 微服务底座。它把 Ollama模型推理、Qdrant向量数据库、Dify应用编排和 API 网关全部编排进 Docker Compose再通过一个 Web 安装向导自动完成环境检测、参数配置、配置生成和一键部署。整个过程不需要手写 docker-compose不需要记一堆命令打开浏览器按提示走完六个步骤就能看到服务健康检查全部通过。适合三类人刚入门想本地跑 AI 应用的开发者、要给团队快速搭内部 AI 服务的运维或后端同学以及想在公司内网私有化部署一套 AI 中台的技术负责人。1. 项目整体设计与思路拆解1.1 先拆清楚什么是“AI 微服务底座”很多朋友一听到“微服务底座”就以为是 K8s、Istio 那一套其实在 AI 应用这个场景里底座的核心是四件事模型推理、知识存储、应用编排、统一入口。模型推理负责跑大模型知识存储负责把文档向量化并支持检索应用编排负责把“模型知识工具调用”串成业务能力统一入口负责让外部系统以标准 API 的方式调用整套能力。打个比方这就像开一家餐厅。后厨是模型推理服务负责出菜冰箱和仓库是向量数据库负责存食材知识前台点单系统是应用编排层负责把顾客需求转成后厨能执行的订单而门迎就是 API 网关所有客人从同一个门进来。没有这套底座你的 AI 应用就是一个个孤岛模型只能聊天、知识库只能检索无法组合成真正可用的业务系统。底座这个词的重点在于“可复用”。搭建一次之后上层任何 AI 应用都可以通过 API 接入不用再重新部署模型和向量库。这也是我坚持微服务拆分而不是做成单体应用的原因——模型推理要 GPU向量库要内存编排层要 CPU三者资源需求完全不同拆开才能独立扩缩容。1.2 为什么必须做向导式安装我最早做这套底座的时候是纯手动部署踩过的坑那叫一个多。Ollama 版本要 0.1.3x 以上Qdrant 的镜像 tag 要和 client 版本匹配Dify 依赖 PostgreSQL 和 Redis 两个中间件网关的 upstream 配置写错一个斜杠就 502。这套东西我闭着眼睛能配但换一个人来光看部署文档就得看一个小时中间还要理解一堆“为什么要这样”的背景知识。向导式安装的本质是把这些踩坑经验固化成交互流程。用户不需要知道 Qdrant 为什么要用 volume 挂载数据不需要理解 Dify 的 init 容器为什么要等 PostgreSQL 就绪只需要在界面里选择“我要装知识库问答”向导就会自动生成正确的配置组合。这样做的好处有三个降低门槛。用户只面对业务层面的选择模型选哪个、知识库放哪、端口多少基础设施层的事交给向导处理。消除不确定性。手动部署最大的问题是“配置对不对没人知道”向导在生成配置后可以做预检提前发现端口冲突、资源不足、镜像拉不到等问题。可复制。相同配置可以在多台机器上重复部署非常适合给团队或者客户批量交付。我见过太多“照着教程一步步配最后跑不起来”的情况问题几乎都出在环境差异上有人 Docker 是 19.03 的老版本有人内存只有 8G有人 GPU 驱动没装。向导式安装把这些差异全部变成启动前的检测项不合格直接提示而不是等你跑到第五步才报错。1.3 技术选型与取舍背后的考量选型永远是架构设计里最纠结的部分。我最终定的组合是 Ollama Qdrant Dify APISIX安装向导用 FastAPI React 实现。这套组合并不是性能最强的但它是落地效率最高的。选型时我做了几组对比组件我选的方案替代方案选择理由模型推理OllamavLLM、TGIvLLM 吞吐高但配置复杂TGI 对硬件要求高Ollama 一条命令跑模型天然适合向导化向量数据库QdrantMilvus、ChromaMilvus 组件多偏重集群Chroma 功能偏轻Qdrant 单机够用、有 Web UI、API 设计清爽应用编排DifyFastGPT、LangFlowDify 自带 RAG 管道、Agent 工作流和 API 发布能力社区活跃文档全API 网关APISIXKong、NginxAPISIX 有控制台路由配置可视化对 AI 场景的流控、鉴权支持完善安装向导后端FastAPIDjango、Spring Boot轻量、异步支持好写配置生成逻辑很顺手安装向导前端React ViteVue、Next.js组件生态成熟交互状态管理方便构建产物小我重点说一下为什么没上 K8s。很多朋友一听微服务就说“那你得上 K8s 啊”但在这套底座的落地场景里大多数是单机或者三五台机器的小集群用 K8s 等于杀鸡用牛刀——光装集群就要半天还要维护 etcd、kubelet 这些组件。Docker Compose 用声明式 YAML 描述六个服务之间的关系一条命令拉起对于 10 分钟跑起来的诉求来说是最优解。如果你后续真的要扩到多节点Compose 配置也能比较平滑地迁移到 Docker Swarm 甚至 K8s。2. 核心细节解析与实操要点2.1 底座包含的组件与职责划分这套底座一共编排了七个容器每个容器干一件事职责边界非常清晰。首先是 Ollama 容器负责模型加载和推理默认监听 11434 端口。它会把模型文件存放在挂载目录里保证容器重建后模型不丢。其次是 Qdrant 容器负责向量存储和相似度检索监听 6333API和 6334gRPC数据目录同样用 volume 持久化。然后是 Dify 容器组严格来说它不是一个容器而是 api、worker 和 web 三个容器的组合。api 处理 REST API 请求worker 消费异步任务比如文档解析、索引构建web 是用户操作界面。Dify 依赖 PostgreSQL 存储业务数据、Redis 做缓存和队列所以底座里还包含了这两个中间件容器。最后是 APISIX 网关容器监听 80 端口把所有内部服务统一暴露出去配上密钥校验和速率限制。这里有个容易忽略的点Ollama 默认只监听容器内部的 11434要让 Dify 或者其他服务访问它的模型能力需要在 docker-compose 里把 Ollama 加入 Dify 所在的网络同时把宿主机的 11434 端口映射出来方便直接用 curl 调试。我在向导里默认做了双向映射——既加入内部网络供服务间调用也暴露宿主机端口供开发者直连。资源占用方面Ollama 跑 7B 量级模型大概需要 6~8GB 内存Qdrant 空载大约占 200MBDify 全家桶加中间件合计 2GB 左右。所以整套路底座的最低配置是 12GB 内存建议 16GB 起步。磁盘方面底座程序本身只占 3GB镜像但模型文件才是大头——7B 模型量化后大概 4.7GB14B 模型接近 9GB还要预留知识库向量化的存储空间所以建议预留 50GB 以上。2.2 向导式安装的流程设计这一版向导我设计了六个步骤每一步只让用户做一个决定避免信息过载。第一步是环境检测向导自动检查 Docker 版本、Compose 插件、CPU 核数、内存大小、磁盘剩余空间和 GPU 是否可用不合格的项会标红并给出修复建议。第二步是组件选择用户按需勾选要安装的模块默认全选但可以去掉 API 网关或者只装模型推理。第三步是模型选择。这一步我把 Ollama 官方模型库里适合中文场景的几个模型列成下拉框用户选一个比如 qwen2.5:7b向导会在生成配置时写入自动拉取和启动模型的命令。第四步是存储配置用户指定模型目录、向量库数据目录和 Dify 数据目录的宿主机路径。这里我加了强校验——如果路径已存在且非空会提示是否复用避免误覆盖。第五步是网络配置包括对外服务端口、API 网关的密钥和是否启用 HTTPS。最后一步是预览与部署向导把前面所有选项渲染成完整的 docker-compose.yml展示给用户确认点“开始部署”后执行拉镜像、起容器、初始化数据库、拉模型并在进度条下方实时滚动日志。整个过程部署完成后向导会做一次全链路健康检查返回每个服务的 HTTP 状态码和响应时间。这套流程设计最核心的一个细节是“状态可恢复”。如果部署到一半失败比如拉镜像超时重启向导时会先读取已生成的 compose 文件跳过已经成功的步骤只重试失败的动作而不是让你从第一步重新开始。这个容错机制我后面还会细讲。2.3 部署前的资源评估与前置检查别觉得向导能检测就万事大吉有些问题机器本身检测不出来需要你自己先想清楚。比如 CPU 指令集Ollama 的某些模型在新版本里要求 CPU 支持 AVX2五年前的旧机器可能就带不动。再比如 GPU如果你的机器有 NVIDIA 显卡必须先装好驱动和 NVIDIA Container Toolkit向导检测到 GPU 设备但跑不了推理原因基本都在这里。内存方面有一个很容易被忽视的点Ollama 除了要加载模型权重的内存还有上下文窗口context window的额外开销。默认 2048 上下文时 7B 模型大约额外占 1GB如果你在 Dify 里把上下文调到 8192额外内存会涨到 4GB 以上。所以向导里环境检测的“内存合格线”我定在 16GB最低 12GB 可以装但只能跑小模型。磁盘检测也有讲究。我见过有人把模型目录放在系统盘跑几天硬盘满了系统直接崩溃。向导会提醒模型目录和数据目录不要放在根分区最好是独立的数据盘或挂载卷。检测逻辑里我加了一个“目录所在分区剩余空间”的检查而不是只看当前目录的空闲空间这两个值在跨分区挂载时差别很大。运行df -h 目录路径可以很方便地确认。3. 实操过程与核心环节实现3.1 环境准备Docker 与基础依赖在跑向导之前需要先把基础的运行时环境准备好。我用的是 Ubuntu 22.04 服务器内核版本 5.15以下命令都是在这个环境验证过的。第一步安装 Docker Engine 和 Compose 插件如果之前没装过 Docker可以执行官方脚本一键安装curl -fsSL https://get.docker.com | sh装完确认版本Docker Engine 需要在 24.0 以上因为老版本对 Compose v2 的支持不完整。确认命令docker --version docker compose version我实测下来 Docker 27.x 一切正常Compose v2.24 以上功能完整。然后建议把当前用户加入 docker 组省得每次敲sudo dockersudo usermod -aG docker $USER newgrp docker这里有一个重要提醒如果服务器在国内Docker Hub 的镜像拉取速度经常让人崩溃。向导里面有配置镜像加速的选项也可以在/etc/docker/daemon.json里手动指定加速源并重启 Docker。配置完可以用docker info查看 Registry Mirrors 是否生效。镜像加速是合规操作放心用。GPU 支持方面如果你的服务器有 NVIDIA 显卡需要额外安装 NVIDIA Container Toolkit。装好后在向导的环境检测页面能看到 GPU 型号和显存大小。如果看不到大概率是 toolkit 没装或者驱动版本太旧。3.2 获取安装包并启动向导环境就绪后把向导项目包拷贝到服务器上。我这里为了演示方便直接把向导做成一个 Docker 镜像启动后访问http://服务器IP:8080就能打开安装界面docker run -d --name ai-base-installer \ -p 8080:80 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /opt/ai-base:/data \ registry.example.com/ai-base-installer:latest注意两个挂载/var/run/docker.sock是让向导有权限调用宿主机 Docker 来创建容器这是实现“一键部署”的关键/opt/ai-base是向导的数据目录生成的配置、日志和预检报告都存在这里。第一次启动后打开浏览器进入向导首页界面会先展示一个“环境兼容性总览”绿色的项越多后面的部署越顺畅。启动向导之前建议先做个干净环境检查把 80、443、8080、11434 这些端口能关的关掉避免部署阶段端口冲突。如果 80 被 Nginx 占了在向导的“网络配置”步骤里改成 8081 就行。3.3 向导逐步配置实操我按实际走一遍流程让大家知道每一步怎么填。第一步环境检测正常情况下所有项目都是绿色。如果 Docker 版本这一项标红向导会给出两个按钮一个是“查看修复命令”一个是“重新检测”。修复命令其实就是官方安装脚本复制执行后回来点重新检测就行。第二步组件选择这里默认全选。我建议首次体验全选跑通之后再考虑裁剪。如果只要模型推理和知识库可以取消 Dify 组件这样能省掉 PostgreSQL 和 Redis 两个容器对低配机器来说很友好。第三步模型选择下拉框里列出几个常见模型及其大小qwen2.5:7b约 4.7GB、qwen2.5:14b约 9GB、llama3.1:8b约 4.7GB、bge-m3约 1.2GB纯向量化模型不做对话。对话场景我推荐 qwen2.5:7b中文表现好显存 6GB 就能跑。如果机器只有 CPU选 qwen2.5:7b 的 q4_K_M 量化版也能跑就是生成速度慢一些大概每秒 3~5 个 token。第四步存储配置向导会根据当前磁盘情况给出默认路径/opt/ai-base/models、/opt/ai-base/qdrant_storage、/opt/ai-base/dify_data。我的建议是这些目录不要放在根分区而是放到/data这种独立挂载点下面。填完点“检查路径”向导会验证目录是否可写、空间是否充足。第五步网络配置API 网关端口默认 80模型服务端口可选暴露 11434Dify Web 界面端口 3000管理后台端口 6333。这里我会把 API 网关的访问密钥设成一串随机密钥向导会自动生成你也可以手动改成好记的。HTTPS 选项首次安装先不勾等后面反代加证书。第六步预览配置。这一页会把生成的 docker-compose.yml 完整展示出来你可以看到 Ollama、Qdrant、Dify、APISIX 等服务的定义。确认没问题后点“开始部署”进度条开始走右侧日志窗口会实时滚动显示拉镜像、创建网络、启动容器的过程。整个等待时间取决于网络速度镜像总共 3GB 左右正常网络下 5~10 分钟能拉完。3.4 生成配置的关键内容讲解部署完成后向导会在数据目录下生成完整的部署产物核心文件就是docker-compose.yml。我截取几个关键服务配置说明一下帮你理解向导到底帮你做了什么。模型服务这一段的重点是资源的reservation和limits。我设置了 GPU 保留和内存上限避免 Ollama 把宿主机内存吃满ollama: image: ollama/ollama:latest container_name: ai-ollama restart: always ports: - 11434:11434 volumes: - /opt/ai-base/models:/root/.ollama deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: [CMD, ollama, list] interval: 30s timeout: 10s retries: 3Dify 的编排是这套底座里最复杂的因为它依赖 PostgreSQL 和 Redis而且 api 容器要等数据库就绪后才启动。我用了一个 init 容器配合脚本来处理依赖关系dify-api: image: langgenius/dify-api:0.6.14 container_name: ai-dify-api depends_on: postgres: condition: service_healthy redis: condition: service_healthy environment: DB_HOST: postgres DB_PORT: 5432 DB_USERNAME: dify DB_PASSWORD: ${DIFY_DB_PASSWORD} DB_DATABASE: dify REDIS_HOST: redis REDIS_PORT: 6379 MODE: api volumes: - /opt/ai-base/dify_data:/app/api/storage这里有个细节Dify 在首次启动时会自动执行数据库迁移需要 1~2 分钟中间如果 API 报 503 是正常的。向导的健康检查模块会等 postgres 的 healthcheck 变成 healthy 后再检查 Dify避免误报。APISIX 网关的配置则是把三个服务映射到统一入口并开启 key-auth 插件apisix: image: apache/apisix:3.9.0-centos container_name: ai-apisix ports: - 80:9080 volumes: - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro environment: APISIX_STAND_ALONE: true向导生成的这套配置是经过我反复验证的直接复制到任何一台相同环境的机器上也能跑。这也是向导式安装的另一个价值它产出的不是一次性脚本而是一份可审计、可版本管理的部署资产。3.5 验证与跑通第一个应用部署完别急着开心先做一轮端到端验证确保每个环节都真的通了。第一步检查容器状态确认所有容器都在运行且没有反复重启docker ps --format table {{.Names}}\t{{.Status}}\t{{.Ports}}正常情况下应该看到七个容器状态都是 Up。然后验证模型服务向 Ollama 发一个请求确认模型已加载并可以对话curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 你好用一句话介绍你自己, stream: false }模型如果有响应说明推理链路通了。接着打开 Dify Web 界面默认 3000 端口用向导打印的初始管理员账号登录创建一个应用选择“聊天助手”模型提供商选 Ollama就能直接对话。最后做一个更有代表性的验证——创建一个“知识库问答”应用上传一份 PDF 文档等索引构建完成后提问确认向量检索链路也是通的。我还习惯用 APISIX 网关注册一个 API 再做一次调用确认网关转发正常。你在 Dify 应用页面点“API 访问”复制 API 密钥然后调用网关地址即可curl -X POST http://localhost/v1/chat-messages \ -H Authorization: Bearer app-xxxxx \ -H Content-Type: application/json \ -d {query:你好,inputs:{},response_mode:blocking}如果返回正常回复那这套 AI 微服务底座就算真正跑起来了上层应用可以开始接入了。4. 常见问题与排查技巧实录4.1 Docker 镜像拉取慢或超时这是被问得最多的一个问题现象是部署进度卡在拉镜像阶段日志显示EOF或者timeout。解决思路很直接——配置镜像加速器。在/etc/docker/daemon.json中配置加速源后重启 Docker再重新部署。注意改完 daemon.json 要执行systemctl daemon-reload systemctl restart docker否则不生效。如果你使用向导时环境检测提示 Docker 版本低于 24.0我建议直接升级不要心存侥幸。老版本 Docker 对 Compose v2 的支持是半残的很可能出现docker compose命令不存在的情况。升级方式就是重跑官方安装脚本数据不会丢。4.2 模型下载失败或速度极慢Ollama 拉取模型是从官方源走的网络状况不好时会下载失败。解决办法不使用 Ollama 的拉取命令而是从国内模型社区手动下载模型文件再放到模型目录里。具体做法是# 1. 在 ModelScope 下载 GGUF 格式的模型文件 # 2. 将文件放到 /opt/ai-base/models 对应目录 # 3. 重启 Ollama 容器让模型注册生效 docker restart ai-ollama这里要注意文件名和目录结构必须符合 Ollama 的命名规范否则模型不会出现在列表里。最稳妥的方式是用 Ollama 创建 Modelfile 从本地文件构建模型FROM /path/to/qwen2.5-7b-instruct-q4_K_M.gguf然后执行ollama create qwen2.5:7b -f Modelfile注册模型。这样能绕开所有网络问题部署时间完全可控。4.3 GPU 设备无法使用如果部署向导使用的是 GPU 优化配置但 Ollama 跑起来特别慢或者日志里有 und GPU 的报错先确认 NVIDIA Container Toolkit 是否安装。在宿主机执行docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi如果命令执行失败说明容器无法访问 GPU需要重新安装 toolkit。如果命令成功再检查 docker-compose 里 GPU 的reservation配置是否写对。注意 NVIDIA 驱动版本要跟 CUDA 兼容建议驱动版本 535 以上。4.4 Qdrant 连接被拒绝或检索超时Dify 配置向量数据库时填了 Qdrant 地址但提示连接失败通常是两个原因。第一是网络没通确认 Qdrant 容器和 Dify 容器在同一个 Docker 网络里用docker network inspect查看。第二是 Qdrant 还没完全启动它的健康检查接口在/readyz返回 200 才算就绪。在向导的部署日志里能看到 Qdrant 的启动状态等它就绪再让 Dify 连接。还有一种情况是 Dify 对 Qdrant 的 API 版本兼容问题我的建议是把 Qdrant 镜像固定在 1.9 以上版本旧版本的部分字段 Dify 读取会报错。升级 Qdrant 时注意备份qdrant_storage目录避免数据丢失。4.5 端口冲突导致服务无法启动安装向导在部署前会做端口预检但依然可能漏掉少数场景。比如有服务监听了 3000 端口Dify Web 就起不来。排查方法很简单先用ss -lntp | grep 端口号查看占用进程然后在向导的“网络配置”步骤改端口映射即可。有一个经验之谈Dify Web 我建议映射到一个冷门端口像 23000因为 3000 端口在开发机上太容易被占用了。部署遇到问题先不要慌很多看起来复杂的问题都是小配置导致的。我把常见问题整理成了速查表方便你对照处理故障现象可能原因解决动作部署卡在拉镜像网络慢或无镜像加速配置 Docker 镜像加速器后重启 Docker模型下载失败Ollama 官方源网络差用 ModelScope 下载 GGUF 后本地注册GPU 不可用NVIDIA Container Toolkit 未装安装 toolkit 并用--gpus all测试Qdrant 连接拒绝容器尚未就绪或网络隔离检查/readyz状态和 Docker 网络Dify Web 打不开端口冲突修改端口映射并重启容器容器反复重启配置错误或资源不足查看docker logs 容器名定位问题对话回复慢模型量化等级高或 CPU 模式换小模型或开启 GPU 推理4.6 向导中途失败后的恢复策略我前面提到向导有“状态可恢复”机制这里展开讲一下。向导会把每一步的执行结果记录到/opt/ai-base/installer/state.json里面标记了每个步骤是 pending、completed 还是 failed。如果部署中途失败重新打开向导页面会看到“继续上次部署”的按钮点击后向导会跳过 completed 的步骤只执行 pending 和 failed 的。这样就避免了重复拉取已经存在的镜像。如果部署失败后你想彻底重置向导首页有“重置环境”按钮它会执行docker compose down -v并清空数据目录。注意这个操作会删除所有向量数据和模型文件谨慎使用。我在按钮上加了两层确认弹窗提示后果需要手动输入“RESET”才能执行。说实话向导式安装这件事做到后面我发现最难的倒不是技术而是把你脑中那些“理所当然”的细节全部显性化。比如 Qdrant 要等就绪、Dify 迁移要 1 分钟、Ollama 模型名里不能有斜杠这些经验不写进逻辑里别人就会反复踩坑。把经验沉淀成交互流程让后来者不踩坑这才是我做这套东西最大的收获。最后再分享一个实用的小技巧第一次部署跑通之后把/opt/ai-base目录整体备份一份或者提交到 Git 私有仓库。以后再部署新环境直接用这份配置改几个路径和密钥就能批量复制。如果你后面想把底座升级到多节点这套 Compose 配置也可以作为 Docker Swarm 或 K8s 的起点。按照这个思路祝你也早日跑起自己的 AI 底座。