适用场景与准备工作
Sourcegraph Cody 作为面向开发者的 AI 代码搜索与编程助手工具，能够在主流编辑器中高效完成代码解释、智能重构建议、单元测试自动生成、跨文件问答以及代码补全等任务。默认情况下，多数团队会选用在线模型服务，但在内网开发环境、私有仓库管理、成本控制需求或对响应稳定性要求较高的场景中，将 Cody 接入本地模型无疑是更优选择。需要明确的是，所谓本地模型，并非把 Cody 本身改造成模型程序，而是让 Cody 通过本机或局域网内部的推理服务来调用大语言模型，从而实现本地化运行。
在开始之前，建议提前准备以下三类条件：第一，安装 VS Code 或 JetBrains 系列 IDE，并完成 Cody 插件的安装；第二，准备能够运行本地模型的推理框架，例如 Ollama、LM Studio 或兼容 OpenAI API 的本地推理服务；第三，确认硬件资源配置。通常，7B 级别的代码模型推荐 16GB 内存起步，若希望获得更加流畅的代码补全体验，建议配备独立显卡及充足显存。即便是笔记本电脑也能运行小尺寸模型，但需要接受首 token 延迟较高和长上下文场景下速度下降的现实。
模型选择与下载思路
在代码场景中，应优先选择偏重编程能力的模型，例如 Code Llama、Qwen Coder、DeepSeek Coder、StarCoder 系列等。模型尺寸并非越大越好，关键在于机器能否稳定承载。日常用于解释代码、生成注释、补充测试用例时，7B 或 8B 量级的模型通常已足够使用；而对于复杂重构、跨模块分析等任务，可考虑 14B 以上的模型，但这将对显存、内存和散热能力提出更高要求。
如果使用 Ollama，模型下载通常通过命令行完成，例如拉取指定的代码模型后，Ollama 会自动将模型文件存放于默认模型目录，并在本机提供推理服务。使用 LM Studio 时，可在软件内直接搜索模型并下载 GGUF 格式文件，随后启动本地服务。企业环境中，也可以提前从合规来源下载模型文件，放入统一目录，确保版本、量化格式和许可证均可追溯。模型下载完成后，不要急于接入 Cody，建议先在本地推理工具中提问几段代码，确认模型能够正常回答、响应速度可接受、上下文长度符合预期。
本地推理服务启动与路径设置
以 Ollama 为例，安装完成后先启动服务，再运行模型。默认服务地址通常为本机的 11434 端口。若 Cody 支持直接选择 Ollama 作为提供方，可在插件设置中填写服务地址和模型名称；如果当前版本需要使用 OpenAI 兼容接口，则可选择支持该接口的推理服务，或通过中间层将本地模型暴露为标准接口。
在 VS Code 中，进入设置页面搜索 Cody，重点检查模型提供方、Chat 模型、Autocomplete 模型、API Endpoint 等选项。Chat 模型负责问答、解释和生成较长内容，Autocomplete 模型则负责行级或块级补全。两者可以使用不同的模型：问答任务选用能力更强的代码模型，补全任务则使用体积更小、响应更快的模型。配置路径时需注意三点：地址必须包含正确的协议和端口；模型名称必须与本地服务中的名称完全一致；如果服务需要密钥，应填入本地服务约定的占位密钥或真实访问令牌。
JetBrains 插件的配置思路类似，在设置中找到 Cody 相关配置，选择模型来源并填写本地服务地址。完成配置后，新建一个小型测试项目，打开 Cody Chat，输入“解释当前文件的主要功能”或“为这个函数生成测试用例”，观察是否能够正常返回结果。若返回连接失败，多半是由于服务未启动、端口不一致、防护软件拦截或插件版本暂不支持该接口格式所致。
代码索引与上下文配置
Cody 的优势不仅在于模型回答本身，还在于结合仓库上下文理解代码的能力。本地模型接入成功后，应继续检查仓库索引状态。小型项目可以直接让 Cody 读取当前工作区；大型单体仓库则建议排除构建产物、依赖目录、日志文件和大体积二进制文件，避免无效上下文拖慢检索效率。
常见的排除对象包括 node_modules、dist、build、target、.cache、coverage、临时文件目录以及自动生成的接口文件。合理的排除规则能够有效降低索引负担，同时让模型更容易命中真正有价值的业务代码。对于多语言项目，建议从核心服务目录开始测试，而不是一次性将所有仓库都交给 Cody 处理。
如果团队已经部署了 Sourcegraph 实例，可让 Cody 借助 Sourcegraph 的代码搜索能力完成更准确的跨仓库检索；如果只是个人开发环境，也可以先使用本地工作区上下文。无论采用哪种方式，都需要明确一点：模型越大不代表上下文越准确，检索结果质量、提示词组织和文件范围控制同样至关重要。
性能优化：速度、内存与补全体验
本地模型性能优化首先要关注模型大小和量化格式。显存有限时，优先选择 Q4 或 Q5 量化版本；追求质量可尝试 Q6、Q8，但资源占用会明显上升。若机器在回答时出现系统卡顿、编辑器无响应，说明模型过大或并发设置过高，应降低模型规格，或将补全模型与对话模型分开部署。
其次是上下文长度。长上下文有利于理解复杂项目，但会增加推理耗时。日常补全不需要过长的上下文，建议为补全模型设置较短的上下文长度以换取低延迟；代码审查、架构分析等任务再使用较长的上下文。第三是并发控制。本地推理不适合无限并发，多窗口同时请求会导致排队。个人使用可保持默认并发，团队共享服务则应限制请求数量，并监控内存、显存和温度。
第四是提示方式。向 Cody 提问时，尽量指定文件、函数、目标和约束，例如“只基于当前文件说明登录流程，不要改动接口名称”，比笼统地问“优化一下代码”更容易获得可执行的建议。补全体验不佳时，可尝试关闭过于激进的自动补全，改用手动触发，避免模型在每次输入时都发起请求。
常见问题排查
问题一：Cody 显示无法连接模型。首先确认本地推理服务正在运行，然后用浏览器或命令行访问服务地址，检查端口是否正确。若服务部署在另一台机器上，还需确认编辑器所在电脑能够访问该地址，并检查本机安全策略是否已放行。
问题二：能连接但回答很慢。这通常与模型过大、量化不合适、上下文过长或硬件资源不足有关。建议先换用小一档的模型进行测试，再减少上下文长度，关闭其他占用资源的程序。对于补全场景，推荐使用轻量模型以保证交互流畅。
问题三：回答与项目不相关。检查 Cody 是否正确读取了工作区，排除规则是否误排了核心目录，当前文件是否已保存。在大型项目中，最好在问题中明确指出模块、文件名或函数名，让检索范围更加明确。
问题四：插件设置项与教程不一致。Cody 更新较为频繁，不同版本的界面名称可能有所变化。遇到这种情况，应以插件官方设置说明为准，重点寻找模型提供方、接口地址、模型名称和访问令牌这几个核心配置项。
安全边界与实用建议
本地模型能够降低代码外发风险，但这并不等同于绝对安全。配置前应确认推理服务地址仅在可信范围内开放，避免将本地端口暴露给不必要的网络环境。团队使用时，要明确哪些仓库允许接入 AI 工具，哪些密钥、配置文件、客户数据不能进入上下文。即使是本地模型，也建议通过忽略规则排除 .env、证书、私有配置和敏感日志文件。
模型输出应被视为“建议”而非最终答案。涉及鉴权、支付、数据删除、权限控制等关键逻辑时，必须由开发者复核，并通过测试覆盖进行验证。生成的代码还需检查许可证、依赖来源和边界条件，不能直接复制到生产分支。
实践中较为稳妥的方案是：先用小模型打通 Cody 的本地调用链路，再逐步替换为更强的模型；先在个人项目或非核心仓库试运行，再推广到团队；先优化排除规则和提示方式，再盲目升级硬件。只要模型下载、路径设置、上下文索引和性能参数配置得当，Cody 完全能够在本地环境中提供稳定、高效的代码问答与辅助开发体验。
