Gemini CLI本地模型运行教程：下载、设置与性能优化

适用场景与准备工作

Gemini CLI常被用于终端内的代码解释、文档生成、脚本辅助和批量文本处理。若希望减少对外部服务的依赖，或需要在局域网、实验环境中运行模型，可以将其配置为连接本地推理服务。需要明确的是：CLI本身通常是命令行交互层，本地运行的核心在于后端推理引擎，例如Ollama、llama.cpp、LM Studio或其他兼容OpenAI接口的服务。Gemini CLI负责发送请求并展示结果，本地模型则负责实际内容生成。

开始前建议准备三类资源：第一是硬件，日常文本任务建议至少16GB内存；运行7B级量化模型更为稳妥，13B及以上模型对显存和内存的要求明显更高。第二是磁盘空间，常见量化模型从数GB到数十GB不等，应预留模型文件两倍以上的空间。第三是系统环境，Windows、macOS、Linux均可使用，但路径写法、权限设置和后台服务启动方式有所不同，配置时需按系统区别处理。

安装Gemini CLI与本地推理后端

安装Gemini CLI前，先确认本机已具备Node.js或官方要求的运行环境。可在终端输入node -v检查版本，若提示不存在，需先安装长期支持版本。随后使用npm安装对应的CLI包，安装完成后执行gemini --version或相近版本检查命令，确认命令可被系统识别。如果终端提示“command not found”，通常是全局包目录未加入PATH，需重新打开终端或手动补充环境路径。

本地推理后端可依据个人习惯选择。Ollama适合新手，模型管理简单，拉取、运行和更新都比较直观；llama.cpp适合希望细调参数、追求轻量部署的用户；LM Studio适合偏向图形界面的用户，也能提供本地接口。无论选择哪一种，都要确认它能在本机开放一个HTTP接口，并兼容常见的聊天补全格式。后续Gemini CLI只需将请求地址改为本地地址，例如http://127.0.0.1:11434或本机其他端口。

模型下载与选择建议

模型下载应优先选择来源清晰、说明完整、社区反馈较多的版本。常见选择包括通用对话模型、代码模型、长文本模型和中文增强模型。新手不建议一开始就下载体积最大的模型，7B或8B级别的量化版本更适合验证流程。量化格式可降低内存占用，常见的有Q4、Q5、Q8等，数值越高通常质量更优，但资源消耗也相应提升。若主要用于代码解释和命令生成，可选择代码能力更强的模型；若主要进行中文写作和总结，则可选择中文表现更稳定的模型。

下载方式取决于后端工具。使用Ollama时，可通过ollama pull 模型名拉取，完成后用ollama list查看已安装模型；使用llama.cpp时，通常需要手动下载GGUF文件，并保存到固定目录；使用图形工具时，可在模型库中选择下载位置。建议建立统一目录，例如D:\AIModels或/Users/用户名/AIModels，避免将模型分散在下载目录、桌面和临时文件夹中，这样后期迁移和备份会更加方便。

路径设置与环境变量配置

路径配置分为两层：模型文件路径和CLI访问地址。模型文件路径由本地推理后端读取，例如llama.cpp启动时需要指定-m参数指向GGUF文件；Ollama通常将模型存放在自己的管理目录中，用户无需手动指定单个文件。CLI访问地址则用于告知Gemini CLI将请求发送到何处。若CLI支持配置文件，可在配置项中设置baseURL、model、apiKey等字段；若支持环境变量，可设置GEMINI_BASE_URL、GEMINI_MODEL或工具文档中指定的变量名。

在Windows中设置环境变量时，需注意反斜杠可能需要转义，路径中有空格时应使用英文引号。macOS和Linux中可把变量写入.zshrc、.bashrc或当前Shell配置文件，修改后执行source使其生效。为避免误连到外部服务，建议将本地地址明确写成127.0.0.1，并在首次运行时查看后端日志，确认请求确实到达本机服务。

连接本地模型的基本流程

推荐按“先后端、再CLI、最后任务”的顺序排查。第一步，启动本地推理服务。例如Ollama需要先确认后台服务已运行，再执行模型测试命令；llama.cpp可通过server模式启动，并指定模型文件、端口、上下文长度和线程数。第二步，用简单请求验证后端能否返回内容，可使用后端自带命令或本机HTTP测试工具。第三步，打开Gemini CLI，将模型名和接口地址指向本地服务。第四步，输入一个简短问题，例如“用三句话解释递归”，观察响应速度、中文质量和日志输出。

如果CLI默认要求鉴权字段，而本地服务不校验，可填入占位值，例如local-key，但不要将真实密钥写入公开脚本。团队环境中建议使用.env文件或系统变量保存配置，并将包含个人信息的配置文件加入忽略列表，避免提交到代码仓库。

性能优化：从模型、参数到硬件

本地模型运行速度主要受模型规模、量化级别、上下文长度、CPU线程、显存和磁盘读写影响。若响应较慢，优先尝试更小的模型或更低位的量化，而不是盲目提高线程数。线程数通常设置为物理核心数或略低，过高可能造成系统卡顿。上下文长度也并非越大越好，长上下文会显著增加内存占用，日常问答可先设为4096或8192，只有在处理长文档时再适当提高。

有独立显卡的设备可开启GPU卸载，将部分层放到显存中计算。参数名称因后端而异，llama.cpp常见为ngl或gpu-layers，Ollama则可自动适配部分硬件。显存不足时会出现启动失败、速度异常下降或系统变得不稳定，此时应减少卸载层数、换用更小模型或降低上下文长度。磁盘方面，建议将模型放在固态硬盘上，首次加载会更快。笔记本用户还需注意电源模式，节能模式会明显限制推理速度。

常见问题与排查方法

问题一：CLI提示连接失败。先确认后端服务是否启动，再检查端口是否一致，最后确认地址没有写成错误的主机名。问题二：模型名不存在。Ollama用户可执行列表命令查看真实名称，llama.cpp用户需确认启动服务时使用的模型标识与CLI配置一致。问题三：中文输出质量差。可换用中文能力更强的模型，并在系统提示中要求使用简体中文回答。问题四：回答中断或报内存错误。通常是上下文过长、模型过大或并发请求过多所致，需要适当降低参数。

问题五：速度忽快忽慢。可能是后台任务占用资源、设备温度过高、模型首次加载尚未完成，也可能是系统将进程调到了低优先级。可以关闭不必要的软件，观察CPU、内存和显存占用情况。问题六：CLI能连上但返回格式异常。说明本地接口与CLI期望的格式不完全一致，可尝试开启OpenAI兼容模式，或更换支持度更好的后端。

安全边界与使用建议

本地部署并不等于没有风险。模型文件可能包含来源不明的配置或脚本，下载前应查看发布者信息、校验文件完整性，并避免运行陌生的安装脚本。不要将包含密钥、客户资料、未公开代码的内容随意输入到不可信的模型或插件中。即使在本机运行，也要注意日志文件可能记录提示词和输出内容，团队设备应定期清理敏感日志。

对开发者来说，Gemini CLI接入本地模型最适合做可控的辅助工作，例如代码摘要、单元测试草稿、文档初稿、提交说明和批量格式整理。对于需要高准确率的生产操作，应保留人工复核流程。建议先建立一个小模型用于日常快速问答，再准备一个质量更高的模型处理复杂任务；同时将配置文件、模型目录、启动脚本和参数说明记录下来，方便迁移到新设备或交给团队成员复用。

结语：先跑通，再精调

完整流程可以概括为：安装CLI，选择本地推理后端，下载合适模型，设置模型路径和本地接口地址，验证连接，再围绕速度、质量和资源占用逐步调参。不要一开始就追求最大模型和最高参数，先用轻量模型跑通链路，确认任务效果后再升级模型规模。这样既能降低故障排查难度，也能让Gemini CLI在本地环境中稳定承担日常AI命令行任务。