Yi 安装环境怎么配？Docker 一键部署教程，避坑版检查清单

先判断：你的机器适不适合跑 Yi

Yi 系列模型常用于本地问答、文本生成、知识库原型、接口联调和私有化测试。用 Docker 部署的好处是环境干净、迁移方便、失败后容易回滚，不必在主机上反复安装 Python、CUDA、推理框架等依赖。但部署前要先确认目标：只是体验聊天，还是要提供 API 服务；是 CPU 低速测试，还是 GPU 推理；是单人使用，还是要接入业务系统。目标不同，配置方案会明显不同。

硬件方面，CPU 模式可以启动，但速度较慢，更适合连通性验证。想获得可用体验，建议使用支持 CUDA 的 NVIDIA 显卡，并预留足够显存。小参数量或量化版本对资源要求较低，大参数量模型需要更高显存和内存。磁盘也不要忽略，镜像、模型文件、缓存和日志会持续占用空间，建议至少预留几十 GB 可用容量。内存不足时容易出现容器被系统结束、响应卡住或模型加载失败。

部署路线怎么选

常见路线有两种。第一种是使用 Ollama 容器，适合新手快速体验，命令少，模型管理简单，适合本地测试、轻量接口调用和演示环境。第二种是使用 vLLM、Text Generation Inference 等推理服务，适合需要 OpenAI 风格接口、更高并发或更精细参数控制的场景，但配置更复杂，对显卡驱动和模型目录要求更严格。

避坑建议是：第一次部署不要直接追求最大模型，也不要同时改太多参数。先用小模型或量化版本验证 Docker、显卡、端口、模型拉取、接口访问都正常，再替换为目标模型。这样出现问题时，能快速判断是环境问题、资源问题还是模型文件问题。

基础环境检查清单

部署前先做五项检查。第一，确认系统版本。Linux 服务器更适合长期运行；Windows 或 macOS 可用于本机体验，但生产环境建议使用稳定的 Linux 发行版。第二，确认 Docker 可用，执行 docker --version 能返回版本号，docker run hello-world 能正常运行。第三，确认 Docker Compose 可用，执行 docker compose version 检查版本，旧式 docker-compose 也能用，但命令写法略有差异。

第四，若使用 GPU，必须确认主机显卡驱动正常，执行 nvidia-smi 能看到显卡信息。还需要安装 NVIDIA Container Toolkit，使容器能调用 GPU。检查命令可用 docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi，如果容器内也能看到显卡，说明 GPU 通道基本打通。第五，确认端口未被占用，例如 Ollama 默认常用 11434，vLLM 常用 8000，可用 ss -lntp 或 lsof -i 查看。

方案一：用 Ollama 容器快速启动

适合初次上手的方式是启动 Ollama 服务容器。先创建数据卷，避免容器删除后模型丢失：docker volume create ollama。CPU 测试可执行 docker run -d --name yi-ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama。GPU 环境则增加 --gpus all：docker run -d --gpus all --name yi-ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama。

容器启动后，进入容器拉取或运行 Yi 相关模型，例如 docker exec -it yi-ollama ollama run yi。不同模型名称会随平台维护情况变化，若提示找不到模型，应到模型列表确认准确名称，也可以使用自定义 Modelfile 导入本地模型。服务启动后，可通过 http://主机IP:11434 调用接口，或在同一台机器上用 curl 进行测试。若只是本机使用，建议不要把端口暴露到公网，避免无关访问消耗资源。

方案二：用 vLLM 提供接口服务

如果需要更接近服务端部署，可使用 vLLM。前提是显卡、驱动、容器运行时已经配置好，并准备好模型目录或可访问的模型仓库。示例思路是把主机模型目录挂载到容器内，再启动 OpenAI 兼容接口。命令通常包含 --gpus all、-p 8000:8000、-v /data/models:/models，并在启动参数里指定 --model /models/yi-model。具体镜像版本要与 CUDA、驱动和 vLLM 版本匹配，不建议随意使用 latest 标签，最好固定版本，便于复现和回滚。

vLLM 的关键参数包括 max-model-len、gpu-memory-utilization、tensor-parallel-size 等。显存紧张时可降低上下文长度，或选择量化模型；多卡部署时再考虑张量并行。若启动时报 CUDA out of memory，优先检查模型大小、上下文长度、并发数和显存占用，不要只反复重启容器。

模型文件与目录管理

模型来源要可靠，优先使用官方或可信社区发布的权重与量化文件，并留意许可条款、适用范围和更新记录。下载后建议按目录管理，例如 /data/models/Yi-6B、/data/models/Yi-9B-Chat，不要把多个模型混放在同一层级。容器挂载时使用只读参数更安全，例如 -v /data/models:/models:ro，可降低误删风险。

如果模型加载失败，常见原因包括文件未下载完整、目录层级不对、配置文件缺失、文件权限不足、模型格式与推理框架不兼容。排查时先看容器日志：docker logs yi-ollama 或 docker logs vllm-server，再进入容器确认路径是否存在。不要看到报错就重装 Docker，很多问题只是路径或权限写错。

常见问题与处理方法

问题一：容器启动后立刻退出。先用 docker ps -a 查看状态，再用 docker logs 查看报错。若提示端口占用，更换映射端口；若提示权限不足，检查挂载目录属主和读写权限；若提示找不到命令，检查镜像是否正确。

问题二：接口能访问但回答很慢。CPU 模式慢是正常现象；GPU 模式则检查 nvidia-smi 是否有进程占用显存，确认容器是否真的使用了 --gpus all。还可减少上下文长度、降低并发、换用量化版本。问题三：下载模型失败。可改用手动下载后挂载目录，或配置企业内部镜像源。问题四：中文效果不稳定。应确认使用的是 Chat 版本还是 Base 版本，Base 更适合继续训练或二次开发，直接对话体验通常不如 Chat 版本。

安全边界与运行建议

本地部署不等于没有风险。模型输入可能包含业务资料、用户文本或内部文档，日志中也可能记录请求内容。建议关闭不必要的访问入口，接口前增加鉴权或仅允许内网访问；日志保留周期要可控，敏感数据不要直接写入明文日志。对外提供服务时，还要设置限流、超时、最大输入长度和错误返回策略，避免单个请求占满资源。

容器层面建议固定镜像版本，定期更新基础镜像，删除不用的旧模型和悬空镜像。启动命令不要使用过高权限，除非确有必要，不要挂载整个根目录。生产环境应配置健康检查和自动拉起策略，例如 --restart unless-stopped，同时把模型目录、配置文件和启动脚本纳入备份。升级前先记录当前镜像版本、模型版本、启动参数和测试样例，出现兼容问题才能快速回退。

避坑版最终检查表

上线或交付前按这张清单过一遍：Docker 与 Compose 可用；GPU 机器在主机和容器内都能执行 nvidia-smi；端口未冲突且访问范围受控；模型文件来源可靠、目录清晰、权限正确；镜像版本固定，不依赖 latest；启动参数写入脚本或 compose 文件，避免靠手工记忆；已验证最小请求、长文本请求和异常请求；日志位置、容量和保留周期明确；资源限制、并发限制和超时设置已配置；升级与回滚路径已记录。

对于个人学习，Ollama 容器通常最快；对于团队开发，建议使用 Compose 固化服务；对于高并发接口，优先评估 vLLM 等推理框架。Yi 的部署难点不在某一条命令，而在硬件、驱动、模型格式、端口和权限的匹配。先小步验证，再逐步加模型、加参数、加并发，是最省时间也最稳妥的安装思路。