本地部署大语言模型LLM这件事我自己最常被问的不是“模型怎么选”而是“这堆命令到底该怎么敲、为什么这么敲”。很多人装完 Ollama、下载好模型结果卡在环境检查、服务启动、接口验证和容器部署上问题多半出在命令用得不熟。这篇文章就是一份我折腾本地部署 LLM 时的常用命令笔记从系统环境检查开始到模型拉取、服务启停、接口验证、Docker 部署、密钥保护再到问题排查按实际部署顺序走一遍。先澄清一个很多新手绕晕的点DeepSeek、Qwen 这些属于 LLM大语言模型Ollama、llama.cpp、vLLM 是部署工具Agent 是基于 LLM 封装出来的应用。这篇文章的命令主要覆盖“本地部署 LLM”这一段适合刚入门本地部署、或者已经在部署但总在命令行上卡壳的朋友。看清楚每一个命令在做什么比背下来更重要。1. 本地部署 LLM 前先把这套“地基命令”捋清楚1.1 为什么本地部署离不开命令行图形界面工具现在确实越来越多Ollama 桌面版、LM Studio 都能点鼠标操作。但真到了部署阶段GPU 驱动是否匹配、端口有没有被占、模型文件有没有下载完整、容器有没有拿到显卡这些问题图形界面往往给你一个模棱两可的报错。命令行强就强在“每一层都能被看见”。nvidia-smi能显示显存和进程ollama list能确认模型有没有真正落盘ss -tlnp能告诉你端口到底被谁监听。命令行还有一个容易被低估的优势可以脚本化。部署这件事不是只做一次转换机器、更新配置、帮同事复现问题都需要重复执行同一套操作。把验证环境、启动服务、跑接口测试写成脚本下次直接执行能省掉大量重复劳动。我自己的工作目录里永远放着check_env.sh和smoke_test.sh两个脚本前者检查环境后者验证模型是否正常回复。1.2 环境检查三板斧系统、显卡、内存在拉模型之前先确认这台机器到底能不能跑。我的固定套路是执行下面几条命令uname -a cat /etc/os-release nvidia-smi free -h df -hcat /etc/os-release看发行版和版本能避免下载了和系统不匹配的二进制包。nvidia-smi是关键右上角有个 “CUDA Version”很多新手以为这就是已安装的 CUDA 工具包版本其实它只是驱动支持的最高版本。PyTorch、Ollama 这些框架会自带运行时只要驱动版本够新就能跑。显存大小直接决定你能跑多大的模型。我的经验值参考7B 模型量化后大约需要 4-6GB13B 模型量化后大约 8-10GB70B 模型量化后大约需要 40GB 以上。free -h看内存df -h看磁盘。模型文件动辄十几个 GB磁盘满会导致下载中断或模型损坏。检查完这三样心里就有数了不会下载一个根本带不动的模型浪费时间。1.3 用虚拟环境隔离 LLM 依赖LLM 相关 Python 项目依赖冲突是家常便饭。同一个环境里一个项目要 torch 2.1另一个要 2.3直接全装系统里迟早出问题。所以我在本地部署相关框架时第一步永远是建虚拟环境python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install torchvenv是 Python 自带的虚拟环境工具。激活之后终端提示符前面会出现(venv)这时候pip install装的包只进当前目录下的venv不会污染系统 Python。如果你习惯用 conda也可以这样conda create -n llm python3.10 -y conda activate llm实操里有个容易踩的坑新开一个终端后忘记激活虚拟环境直接执行pip install结果装到了系统环境。每次操作前先看一眼提示符或者用which python确认路径是不是指向虚拟环境。如果 pip 下载慢可以配置可信的镜像源但要注意不同镜像的同步频率不一样有些新包可能会晚几天才出现。2. 模型拉取与文件管理从 Ollama 到 Hugging Face2.1 Ollama一条命令完成模型下载和启动Ollama 是目前本地部署最省事的工具它把模型下载、格式转换、服务启动封装得很好。我常用的命令大概这几条ollama pull deepseek-r1:7b ollama list ollama show deepseek-r1:7b ollama run deepseek-r1:7b ollama stop deepseek-r1:7b ollama rm deepseek-r1:7bollama pull负责下载模型冒号后面的 tag 是版本标识比如deepseek-r1:7b就是 7B 参数的版本。ollama list看本地已有哪些模型ollama show看模型详细信息包括参数量、上下文长度、量化等级。ollama run会进入一个交互式对话界面如果本地没有对应模型它还会自动帮你拉取。实际操作建议用ollama show先看模型元信息再决定跑不跑。有一次我以为拉的是一个小模型结果ollama show一看是 70B 的量化版直接把显存撑爆了。另外ollama run只适合手动测试脚本化调用应该直接请求它的 API不要用交互界面。2.2 用 huggingface-cli 拉取模型仓库Ollama 没收录的模型或者你想拿原始权重做微调就需要从 Hugging Face 下载。最直接的工具是官方命令行客户端pip install -U huggingface_hub huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct默认会下载整个仓库包括权重、配置文件、分词器甚至可能有多个格式的权重文件。如果只想下载特定文件用--include过滤huggingface-cli download Qwen/Qwen2.5-7B-Instruct --include *.safetensors --local-dir ./models/Qwen2.5-7B-Instruct下载缓存默认在~/.cache/huggingface可以通过设置HF_HOME这个环境变量改变位置。下载大文件时官方客户端支持断点续传网络中断后重新执行会从断点继续不用从头开始。实操心得下载之前先打开仓库页面看一眼文件列表。有些仓库同时放了pytorch_model.bin和*.safetensors不指定--include就会两个都下白白浪费一两百 GB 空间。另外可以装hf_transfer加速下载执行pip install hf_transfer后设置export HF_HUB_ENABLE_HF_TRANSFER1大文件下载速度会有明显提升。2.3 llama.cpp 场景下的模型转换命令llama.cpp 是做纯 CPU 推理或者边缘设备部署时绕不开的工具。它不直接跑 Hugging Face 的原始权重需要先转成 GGUF 格式。转换命令大概这样git clone https://github.com/ggerganov/llama.cpp cd llama.cpp python3 -m venv venv source venv/bin/activate pip install -r requirements.txt python convert_hf_to_gguf.py /path/to/Qwen2.5-7B-Instruct --outfile ./models/qwen2.5-7b-q8_0.gguf --outtype q8_0转换完事之后最常用的运行命令是llama-server -m ./models/qwen2.5-7b-q8_0.gguf --host 0.0.0.0 --port 8080--host 0.0.0.0表示监听所有网卡允许局域网其他机器访问如果只想本机访问改成127.0.0.1。这里有个细节转换前确认模型目录里有没有完整的config.json和分词器文件缺文件会直接报错。量化等级方面我日常用得最多的是q4_K_M体积小、效果损失在可接受范围显存充足时会用q8_0效果更接近原始模型。3. 启动推理服务、验证接口和排查故障3.1 前台后台启动服务的正确姿势本地部署时启动服务看起来很简单但“怎么启动”决定了服务能不能稳定跑。最直接的命令是前台启动ollama serve这个命令会把日志直接打到终端适合调试。但如果你是通过 SSH 远程连接服务器直接跑前台命令的话只要 SSH 断开服务就跟着没了。所以我更推荐后台启动nohup ollama serve ollama.log 21 拆开解释一下nohup让进程忽略挂断信号SSH 断开了进程也能继续跑 ollama.log把标准输出写到日志文件21把标准错误也重定向到同一个日志文件最后的是把进程放到后台。查看和停止服务用ps aux | grep ollama pkill -f ollama serve除了nohup还可以用tmux保持会话常驻tmux new -s ollama ollama serve # 按 Ctrlb 然后按 d 脱离会话 tmux attach -t ollamatmux 的优点是重新连上服务器后还能看到实时日志。如果你更习惯 systemd可以写一个 user service 管理 Ollama命令层面就是systemctl --user start ollama、systemctl --user status ollama。我个人的经验调试阶段用前台或 tmux稳定部署用 systemd 或 Docker 比较省心。3.2 用 curl 快速验证 OpenAI 兼容接口不管是 Ollama、vLLM 还是 llama.cpp现在都提供 OpenAI 兼容的 HTTP 接口。部署完服务最该做的第一件事就是用 curl 验证接口通不通而不是马上写一大段 Python 代码。以 Ollama 为例curl -s http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-r1:7b, messages: [{role: user, content: 你好}], stream: false }-s是静默模式不显示进度条-H设置请求头-d是请求体这里指定模型名、消息列表。stream设为false是让服务一次性返回完整结果方便查看。如果一切正常会返回一段 JSON里面有content字段和 token 使用量统计。遇到问题时的判断思路404 基本是路径写错了确认是不是/v1/chat/completions401 或 403 是鉴权问题检查有没有配Authorization请求头500 多是服务端推理出错去看服务日志。curl -v可以打印完整请求和响应头是排查连接问题的利器。如果出现curl: (7) Failed to connect先确认端口有没有监听不要急着改代码。3.3 日志、端口和资源占用排查服务的排查三板斧是“日志、端口、资源”。先用tail -f实时看日志再用端口工具确认服务是否在监听最后用nvidia-smi看显存。tail -f ollama.log ss -tlnp | grep 11434 lsof -i :11434 nvidia-smi htopss -tlnp输出里的0.0.0.0:11434表示监听所有网卡外部机器可以访问127.0.0.1:11434表示只监听本机回环地址只能本机访问。如果你想确认服务有没有真的就绪看日志比看端口更靠谱因为有些服务是端口先打开、模型后加载。nvidia-smi执行后注意看Memory-Usage和GPU-Util。显存占用接近上限但 GPU 利用率很低说明模型在等待输入或者并发设置不合理。htop看 CPU 和内存如果 swap 占用很高说明物理内存不够模型可能在频繁换页推理速度会变得非常不稳定。4. Docker 和容器化部署 LLM 的常用命令4.1 Docker 基础命令和 GPU 容器启动容器化部署 LLM 最大的好处是环境隔离。换一台机器只要装上 Docker 和显卡驱动就能把整个服务环境一起带过去。最基础的命令docker pull ollama/ollama docker images docker run -d --name ollama --gpus all -v /mnt/models:/root/.ollama -p 11434:11434 ollama/ollama docker ps docker logs -f ollama docker exec -it ollama bash docker stop ollama docker rm ollama-d表示后台运行--name给容器起名字--gpus all把宿主机所有 GPU 传给容器-v挂载数据卷-p做端口映射。这里的难点是理解“容器内部路径”和“宿主机路径”的区别/root/.ollama是容器内的模型目录/mnt/models是宿主机上的目录两者通过-v绑定到一起容器删掉重建模型数据不会丢。如果启动时提示could not select device driver with capabilities: [[gpu]]别慌这不是镜像问题而是宿主机缺少 NVIDIA Container Toolkit或者 Docker 没有识别到 NVIDIA runtime。可以执行docker info | grep -i runtime确认。4.2 用 Docker Compose 编排 Ollama 和 Open WebUI单条docker run命令在服务多之后就不好维护了。我会写docker-compose.yml把 Ollama 和一个 Web 界面比如 Open WebUI一起编排。一个最简配置services: ollama: image: ollama/ollama container_name: ollama restart: always ports: - 11434:11434 volumes: - ./ollama_data:/root/.ollama deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui restart: always ports: - 3000:8080 volumes: - ./openwebui_data:/app/backend/data environment: - OLLAMA_BASE_URLhttp://ollama:11434这个文件里最关键的是OLLAMA_BASE_URL它让 Open WebUI 容器通过 compose 内部网络访问 Ollama 容器服务名ollama在容器网络里会自动解析到对应地址。启动和管理命令如下docker compose up -d docker compose ps docker compose logs -f docker compose downup -d启动所有服务ps看状态logs -f看日志down停止并删除容器。注意down默认不会删除数据卷所以模型数据还在。如果你用 Dify 这类应用平台本地 LLM 服务的地址也可以填成http://ollama:11434原理一样都是走容器网络而不是宿主机端口。4.3 容器资源监控与日志清理容器跑久了最容易出问题的是日志文件越来越大把磁盘塞满。先看占用docker stats docker system df docker system prune -fdocker stats实时看每个容器的 CPU、内存、网络、磁盘用量。docker system df看镜像、容器、数据卷、构建缓存占了多少空间。docker system prune -f清理悬空镜像和未使用的构建缓存能腾出不少空间。单个容器日志过大我常用这个命令快速清空truncate -s 0 $(docker inspect --format{{.LogPath}} ollama)truncate -s 0是把文件大小截断为 0而不是删除文件所以容器依然持有正常写日志的文件句柄。相比直接删日志文件这个方式不会导致容器日志写入异常。5. 配置管理、密钥保护和 Git 命令5.1 防止 API Key 泄露的几个命令行习惯本地部署 LLM 过程中经常要接入外部 API比如嵌入模型、在线模型服务、向量数据库这些服务基本都需要密钥。命令行里最危险的操作就是直接把密钥写进历史记录。反例是这样export OPENAI_API_KEYsk-xxx这条命令如果被写入~/.bash_history等于密钥明文躺在磁盘上。更糟糕的是有人把这种 export 直接写进~/.bashrc每次终端启动都会加载一旦.bashrc被同步到网盘或上传到代码仓库密钥就泄露了。更稳的做法是把密钥放到项目目录的.env文件并收紧权限touch .env chmod 600 .env vi .env # 内容示例 # OPENAI_API_KEYsk-xxx # OLLAMA_BASE_URLhttp://localhost:11434加载时用export $(grep -v ^# .env | xargs)如果只是临时用一次可以这样输入不留在终端输出里read -s OPENAI_API_KEY export OPENAI_API_KEYread -s不会回显输入内容这样密钥不会出现在终端屏幕上但要注意命令历史里依然没有密钥本身。我还会定期检查历史记录有没有泄露grep -r sk- ~/.bash_history ~/.zsh_history 2/dev/null发现了就用history -d 行号删除对应记录。用完密钥后及时unset OPENAI_API_KEY不要让它一直占用环境变量。5.2 用 Git 和 Git LFS 管理部署配置部署配置文件应当纳入版本控制但模型权重和密钥文件不应该。我的习惯是仓库里只放代码、配置模板和脚本模型文件放在 Git 仓库外的独立目录。初始化并提交git init git add .gitignore docker-compose.yml deploy.sh git commit -m init.gitignore至少包含这些内容.env *.gguf *.safetensors __pycache__/.env必须排除但可以提交一个.env.example里面只写变量名和占位符方便其他人参考。如果模型文件真的需要入 Git 仓库用 Git LFS 跟踪git lfs install git lfs track *.gguf git add .gitattributesgit lfs会把大文件替换成指针文件推送到远端时再传输实际内容。实操中要注意 Git LFS 在公共代码平台有配额限制模型权重动不动十几 GB超配额后推送会失败。本地个人项目里我更建议模型不入库直接用文件夹管理。5.3 环境变量设置与查看Ollama 实例Ollama 的很多行为可以通过环境变量调整这是部署时很好用的手段。常用变量export OLLAMA_HOST0.0.0.0 export OLLAMA_MODELS/data/ollama export OLLAMA_NUM_PARALLEL1 export OLLAMA_KEEP_ALIVE5m ollama serveOLLAMA_HOST0.0.0.0表示监听所有网卡局域网内其他机器可以通过你的 IP 访问 Ollama。但这同时也意味着一个风险Ollama 默认没有鉴权机制只要别人知道你的 IP 和端口就能调用你的模型接口。所以这个设置只建议在可信内网使用千万不要部署到公网。查看已有变量printenv | grep OLLAMAOLLAMA_NUM_PARALLEL控制同时处理的请求数显存不充裕就设成 1。OLLAMA_KEEP_ALIVE控制模型在内存里的驻留时间设为0是每次请求完立即释放设成5m是 5 分钟内保持加载避免频繁请求时重复加载模型。6. 本地部署 LLM 的高频命令速查表6.1 Linux 系统命令速查针对模型部署写过太多遍命令我干脆把它们整理成一张表部署时对照着看目标命令查看系统发行版cat /etc/os-release实时查看 GPU 状态nvidia-smi -l 1查看内存占用free -h查看磁盘剩余空间df -h查看目录占用空间du -sh ~/.ollama/models查看监听端口ss -tlnp查找进程ps aux | grep ollama实时看日志tail -f ollama.log在日志里搜索错误grep -rn error logs/增量传输大文件rsync -avP /data/model userserver:/data/打包模型目录tar czf model.tar.gz model-dir这里特别说一下rsync它比scp更适合传大模型。-P支持断点续传和进度显示传输中断后重新执行会跳过已经传完的部分。tar打包模型目录时如果模型文件数量特别多先打包再传通常比逐个传文件更快也更能保持目录结构。6.2 Docker/K8s 常见命令简表Docker 命令在不同项目里高度相似我也整理成速查表场景命令构建镜像docker build -t my-llm:1.0 .启动容器docker run -d --name llm --gpus all my-llm:1.0进入容器docker exec -it llm bash查看所有容器docker ps -a查看容器日志docker logs -f llm停止并删除docker stop llm docker rm llm实时资源占用docker statsCompose 启动docker compose up -d如果你是把模型服务部署到 Kubernetes 集群最常用的命令是kubectl get pods kubectl logs pod-name kubectl describe pod pod-name本地开发阶段Docker Compose 完全够用K8s 更适合多节点、需要自动扩缩容的场景。用kubectl前先确认当前上下文别一不小心连错集群kubectl config get-contexts7. 常见问题与实战排查记录7.1 显存不足与并发控制我在本地部署时遇到最多的问题就是显存不足。常见场景是 Ollama 加载模型时报CUDA error: out of memory或者 vLLM 启动时直接崩溃。排查第一步是看显存被谁占了nvidia-smi ps aux | grep python如果发现其他进程占用了大量显存先结束这些进程。如果模型本身太大就换一个量化程度更高的版本或者换更小参数的模型。Ollama 可以通过环境变量控制并发export OLLAMA_NUM_PARALLEL1 export OLLAMA_MAX_LOADED_MODELS1OLLAMA_NUM_PARALLEL1让 Ollama 同一时间只处理一个请求显存占用会小很多。OLLAMA_MAX_LOADED_MODELS1限制同一时间只加载一个模型避免同时加载多个模型把显存挤爆。7.2 端口占用与模型重复下载启动服务时报address already in use说明端口冲突了。先查谁占着端口ss -tlnp | grep 11434 lsof -i :11434如果是一个旧的 Ollama 进程直接pkill -f ollama serve另一个常见问题是“模型总是下载到一半就失败”或者“重复下载”。遇到这个先别急着重新执行命令看看磁盘空间df -h ~/.ollama模型文件动辄十几 GB空间不足会下载失败。Ollama 的pull本身有层校验机制重复执行不会完全重新下载但如果磁盘满了下载会中断并可能出现层校验失败。这时用ollama rm删除模型再重新拉取不要手动删~/.ollama/models/blobs目录删错文件会造成模型损坏表面上看起来还在列表里加载时却直接报错。7.3 排查命令模板日志→进程→资源三步走我在帮同事排查本地部署问题时基本固定按“日志、进程、资源”三步走效率很高。先看日志通常能直接定位报错原因tail -n 100 /tmp/llm.log再看进程确认服务真的在跑ps aux | grep -E ollama|llama|vllm最后看资源确认不是显存、内存或磁盘瓶颈nvidia-smi free -h df -h日志、进程、资源都正常但接口还是不可用这时候再看调用参数模型名是否存在、JSON 是否合法、messages 里是否包含非法角色、请求头有没有带对。命令行排查最忌讳乱猜一步一步来反而最快。部署完成后我会写一个非常简单的smoke_test.sh里面放好 curl 请求并检查返回状态码和content字段是否非空。换机器、换环境后先跑一遍几分钟就能确认整套部署是否正常。这套“环境、模型、服务、终端验证”的命令组合我用下来几乎覆盖了本地部署 LLM 的大部分场景希望也能帮你少走一些弯路。