? 环境准备：别让依赖问题拖后腿
刚开始鼓捣 Ollama API 本地部署的时候，好多人上来就踩环境的坑。咱先把地基打好，不同系统的坑不一样，得分开说。Windows 用户特别容易在 Python 环境上栽跟头，记得一定要去官网下最新的稳定版，别图省事用系统自带的。安装的时候注意勾选 “Add Python to PATH”，不然之后配置环境变量能折腾你半小时。macOS 用户容易卡在 Homebrew 的版本上，先打开终端敲一句
brew update，把包管理工具更新到最新，省得装依赖的时候报错。Linux 用户更要注意，不同发行版的包管理工具不一样，Debian 系的用
apt-get，RedHat 系的用yum，千万别搞混了。比如装 OpenSSL 的时候，Ubuntu 用户得用sudo apt-get install libssl-dev，CentOS 用户就得换成sudo yum install openssl-devel。还有啊，不管啥系统，最好新建个专门的项目目录，别在根目录下瞎搞，不然之后文件乱成一锅粥，找配置文件都费劲。? 安装步骤：按部就班才是王道
下载源码的时候，好多人图快直接复制链接，结果经常下到旧版本。正确的做法是去 Ollama 的 GitHub 仓库，找到最新的 Release 版本，点击 “Source code (zip)” 下载。解压之后，先别急着跑安装命令，看看目录里有没有
requirements.txt文件，用pip install -r requirements.txt把依赖一次性装上。这里特别容易遇到版本冲突，比如某个包要求 Python 3.8 以上，可你装的是 3.7，这时候就得用pip install python==3.8.10指定版本安装。接下来是编译环节，Linux 和 macOS 用户需要先安装 GCC 编译器，Windows 用户得装 Visual Studio Build Tools。好多人报错说 “找不到编译器”，就是因为没装这个。编译的时候可以加上
--user参数，把程序装到用户目录，避免权限问题。装完之后，先别着急启动服务，用ollama --version检查一下版本，确保安装成功。要是显示 “command not found”，大概率是环境变量没配置好，回到第一步检查 Python 安装时的 PATH 设置。? 配置文件：细节决定成败
Ollama 的配置文件默认叫
config.yaml，好多人找不到在哪，其实就在用户目录下的.ollama文件夹里。打开之后，首先看api_port端口号，要是跟本地其他服务冲突了，比如 8080 被占用了，就改成 8000 或者其他端口。还有model_path，默认是下载到系统盘，C 盘空间紧张的 Windows 用户记得改成其他盘，比如D:/ollama/models，改完之后一定要创建对应的目录，不然服务启动会报错。认证配置这块容易被忽略，要是你打算对外提供 API 服务，一定要设置
api_key，别直接用默认的空值。生成 API Key 可以用随机字符串工具，比如在线生成 16 位的随机码，然后填到配置文件里。还有日志配置，建议把log_level设为info，别用debug，不然日志文件会变得超大，占满硬盘空间。改完配置文件记得保存，然后用ollama config reload命令重新加载配置，不然改动不生效。?️ 服务启动：这些坑让你原地爆炸
启动服务的时候，Windows 用户容易遇到端口被占用的问题，这时候可以用
netstat -ano | findstr "端口号"查看哪个进程占用了，然后用taskkill /pid 进程号 /f杀掉。Linux 和 macOS 用户可能会遇到权限问题，别直接用sudo启动，新建一个普通用户来运行服务，提高安全性。启动命令加上--daemon参数可以让服务在后台运行，但是好多人忘记加，关掉终端服务就停了，记得用ollama service status查看服务状态。还有一种情况，服务启动后访问不了，这时候要检查防火墙设置。Windows 用户打开高级安全防火墙，添加入站规则允许对应的端口；Linux 用户用
ufw allow 端口号/tcp命令放行端口。另外，云服务器用户别忘了在控制台的安全组里开放端口，好多人在本地测试没问题，一放到服务器上就不行，就是因为没开安全组。? API 调用：别让细节毁了你的测试
调用 API 之前，一定要先看文档，Ollama 的 API 文档里有详细的请求示例，好多人自己瞎写参数，结果返回 400 错误。比如发送文本请求，参数名是
prompt，别写成message，内容格式要 JSON.stringify 处理，不然服务端解析不了。认证头Authorization要写成Bearer your_api_key，好多人漏掉Bearer，导致认证失败。测试的时候用 Postman 或者 curl 工具，先测本地
http://localhost:端口号/v1/generate，返回正常了再测远程。返回结果解析也容易出问题，好多人直接取response.text，其实应该解析 JSON，获取data.choices[0].text。还有速率限制，默认每分钟 100 次请求，超过了会返回 429，需要在配置文件里调整rate_limit参数，或者加个重试机制。? 性能优化：让你的部署更丝滑
模型加载这块，好多人把所有模型都放在默认目录，启动的时候全部加载，导致内存占用过高。正确的做法是按需加载，用
ollama model load model_name单独加载需要的模型，不用的及时用ollama model unload model_name释放内存。缓存设置也很重要，在配置文件里把cache_size设为合适的值，比如 2GB，别太大也别太小，太大占内存，太小影响速度。多线程处理方面，Windows 用户注意别开太多线程，CPU 核心数的 2 倍差不多了，Linux 用户可以适当多开一些。还有硬件加速，要是有 Nvidia 显卡，记得安装 CUDA 和 cuDNN，然后在启动命令里加上
--gpu参数，好多人不知道这个，结果用 CPU 跑模型，慢得像蜗牛。磁盘 IO 优化方面，把模型目录放到 SSD 上，比机械硬盘快好几倍，特别是频繁访问模型的时候，效果很明显。? 常见错误处理：手把手教你排雷
遇到 “Model not found” 错误，先检查模型名称是否正确，是不是多了空格或者大小写不对，然后用
ollama model list查看已加载的模型。“Out of memory” 错误，大概率是模型太大，内存不够，关掉其他占用内存的程序，或者换个小一点的模型。“Connection refused” 错误，先确认服务是否启动，端口是否正确，防火墙和安全组是否放行。还有一种情况，日志里显示 “UnexpectedEOF”，这通常是配置文件格式错误，检查是不是有中文逗号或者缩进不对，YAML 文件严格要求缩进，用两个空格，别用 Tab 键。API 返回 “Invalid API key”，检查是不是配置文件里的 API Key 没保存，或者请求头里写错了，注意空格和大小写。遇到不懂的错误，先看日志，定位到具体的报错行，然后去 GitHub 的 Issue 里搜索，大概率有人遇到过同样的问题。
? 升级与维护：让你的部署长治久安
升级 Ollama 的时候，好多人直接覆盖安装，结果配置文件被清空。正确的做法是先备份
config.yaml和模型目录，然后卸载旧版本，再安装新版本，最后把配置文件复制回去。定期清理不用的模型，用ollama model delete model_name，不然磁盘空间会被慢慢占满。日志文件也要定期清理，设置日志轮转，比如每天生成一个新日志，保留 7 天，避免单个日志文件太大。监控服务状态很重要，用
ollama service status定期查看，或者写个脚本每分钟检查一次，发现服务挂了自动重启。还有安全方面，定期更新 Ollama 版本，修复已知漏洞，API Key 别泄露，最好定期更换。遇到大版本更新，一定要看更新日志，好多配置项可能会有变化，比如端口号调整、参数改名等，别直接升级导致服务启动不了。该文章由dudu123.com嘟嘟 ai 导航整理，嘟嘟 AI 导航汇集全网优质网址资源和最新优质 AI 工具
