企业官网建设流程全解析

最近我把 CodeBuddy 桌面端从默认模型换成了自定义模型，然后把常用的提示词、短流程和几个小脚本收拢到一起，搭了一个叫 WorkBuddy 的私人 AI 工作台。折腾下来最大的感受是：官方模型再好用，也不如自己可控的模型让人踏实——不用等接口放量，不用心疼额度，还能按自己的场景调参数。这篇就把整个实战过程记录下来，从选模型、跑本地服务，到让 CodeBuddy 认上这个模型，再到把日常琐事固化成一个工作台，全程有操作步骤、实测参数和踩坑记录，适合正好想给 CodeBuddy 接自定义模型、又希望搭一套趁手工具的开发者参考。

1. 为什么折腾：把 CodeBuddy 桌面端换成自定义模型的真实理由

很多人可能会问，CodeBuddy 桌面端开箱即用，默认模型也够聪明，何必自己接一套？这个问题的答案分两层，一层是思想上的，一层是利益上的。

1.1 官方模型不够用？先盘一下痛点

先说思路。CodeBuddy 这类桌面端工具，默认走的是云端模型服务。云端模型的优点是省心，缺点是三个字：不可控。我在实际使用中至少碰到过三档子烦心事。

第一档是响应不稳定。高峰期请求排队，几十秒不出结果，交互体验直接从“实时对话”退化成“邮件往来”。第二档是上下文连续性差。对话一长，前面的上下文要么被截断，要么被摘要压缩，问着问着它就把我刚才讨论的接口约定忘了。第三档是定制能力弱。默认模型用的是一套通用提示词，我想让它输出某种固定格式的代码评审意见，每次都要在对话里反复交代，交代完它还不一定执行到位。

这三个痛点叠加起来，使用体验其实是打折的。我需要的不是“一个很聪明的模型”，而是一个“听话、稳定、按我的规则办事的模型”。这就是接自定义模型的直接动机。

1.2 自定义模型能带来什么实际收益

把模型换成自定义之后，收益是肉眼可见的。先说成本账。本地模型跑起来之后，我自己的机器就是推理服务器，不再按 token 计费，重度使用一天下来电费可能还没一杯咖啡贵。再加上本地推理没有并发额度限制，我可以同时开三个会话窗口，各问各的，谁也不挤谁。

再说数据隐私。代码片段这种东西，有些人觉得无所谓，但写到核心业务的算法逻辑、内网服务的接口签名时，我还是不想让它们离开自己的机器。本地部署意味着请求不出本机，安心很多。

最后才是真正的杀手锏——定制化。接上自定义模型之后，我可以把 CodeBuddy 桌面端的行为完全调成自己的节奏：换掉它的默认人格，塞进我的提示词模板，甚至可以针对项目的代码风格微调。这种感觉就像买了一套精装房之后自己重新做了软装，住起来舒服多了。

当然，换来这些收益也是有代价的：你得搞定模型服务、接口配置、参数调优。而这篇博文，本质上就是把我这段时间交的“学费”整理成一套可复用的流程。

2. 动手前置：选模型、定接口、搭服务的完整准备

接自定义模型听起来像是个大工程，实际上拆开就三件事：选一个模型、起一个服务、告诉 CodeBuddy 怎么连。三件事里任意一件出岔子都会导致最终失败，所以我按顺序讲，每步的取舍也一并说清楚。

2.1 模型选型的三个原则

自定义模型不是越火越好，也不是参数越大越好。选型时我给自己定了三个原则。

第一，先看硬件再选规模。你的机器有多少显存，决定了你能跑多大的模型。以我自己的机器为例，24G 显存是个分水岭：跑 7B 参数模型可以上高精度量化甚至半精度，跑 13B 只能上中等量化，跑 30B 以上就得谨慎权衡速度了。量力而行，别让模型把机器拖成幻灯片。

第二，优先选支持 OpenAI 兼容接口的模型。这一点极其重要。CodeBuddy 桌面端通常不认识某个模型专属的推理 API，但它几乎都认识 OpenAI 风格的接口协议。所以不管底层是哪个模型，只要外面包一层 OpenAI 兼容接口，就能无缝对接。这个原则帮我省掉了大量适配工作。

第三，关注上下文长度和量化级别。上下文长度决定你们能连续聊多深，量化级别决定同样的显存下能塞进多大的蛋糕。我实测下来，Q4_K_M 量化是性价比最稳的选择：质量比 Q8 略低，但速度几乎快一倍，长时间对话也不会因为显存不足报错。

2.2 OpenAI 兼容接口：自定义模型接入的事实标准

这里值得多讲两句“OpenAI 兼容接口”是什么。它本质上是一套约定俗成的 HTTP 接口规范，定义了模型对话请求长什么样、响应怎么返回。常见的形如/v1/chat/completions的端点，通过POST发送携带model、messages、stream等字段的 JSON，服务端就会返回模型生成的文本。

为什么选它当事实标准？因为生态已经高度统一。CodeBuddy 桌面端支持，其他做 AI 工具的桌面应用支持，各种小工具和脚本也都支持，接一次模型以后到处能用。

我搭的本地模型服务最终就是暴露了一个 OpenAI 兼容端点，这也意味着后续无论 CodeBuddy 怎么升级，只要它还支持自定义服务地址，我这条链路就不会断。从这个角度看，兼容标准接口本身就是一种长期投资。

2.3 搭建一个本地模型服务

模型服务这块，我专门用一个独立目录来管理，跑起来之后是个常驻后台进程。具体步骤大概是：

先下载模型权重，这一步没什么技巧，就是去模型仓库里找到适配你显存的量化版本，把文件拉下来。随后启动服务，指定模型路径、监听端口和上下文长度，我用的是 8192，对日常任务足够了：

local-runner serve --model-path ./models/CodeBuddy-mix-Q4_K_M.gguf --port 11434 --ctx-size 8192

启动之后先在本地用 curl 测一下接口通不通：

curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "codebuddy-mix", "messages": [{"role": "user", "content": "你好"}], "stream": false }'

如果返回了一个带choices字段的 JSON，说明服务正常。一个容易踩的坑是端口占用。本地起服务最常见的问题就是 11434 已被某个旧进程占了，命令行会直接报错，所以起服务前先检查端口：

lsof -i :11434

有输出就先kill掉旧进程再重新拉服务。这个习惯能让你少走很多弯路。

3. 核心实现：给 CodeBuddy 桌面端接上自定义模型

本地服务起来之后，第二步就是把这个服务地址交给 CodeBuddy 桌面端。这一步看着简单，但入口藏得挺深，我第一次找配置项就翻了半天。下面按实际操作顺序走一遍。

3.1 找到 CodeBuddy 的配置入口

CodeBuddy 桌面端的设置入口在右上角用户头像菜单里，点开之后有一项叫“模型服务”或“服务配置”，不同版本可能叫法略有差异。进去之后，你会发现默认选中的是官方服务，底下有几个预设模型的选项，同时还有一个“自定义服务”的开关。

打开“自定义服务”开关后，基本上就是三个字段：服务地址、模型名称、密钥（可选）。这三个字段就是把 CodeBuddy 和本地模型服务对接的关键。

如果 UI 里没有这个入口，还有变通方案。CodeBuddy 桌面端通常会在用户配置目录下放一个配置文件，路径大概长这样：

~/.codebuddy/config.json

里面有类似api_base、model_name的字段，手动编辑之后重启桌面端也能生效。这个方案稍微糙一点，但胜在通用，UI 入口找不到的时候可以走这条路。

3.2 把自定义模型挂到 CodeBuddy

我是直接在 UI 里操作的，三个字段这么填：

• 服务地址：http://127.0.0.1:11434/v1
• 模型名称：codebuddy-mix
• 密钥：空（本地服务不需要鉴权）

重点提醒一个容易出错的细节：服务地址的结尾到底带不带/v1。

我第一次配置时填的是http://127.0.0.1:11434，结果 CodeBuddy 怎么连都报错。排查了半天才发现，它内部会在服务地址后面拼接/chat/completions，而我本地的服务要求路径必须是/v1/chat/completions。所以服务地址必须带/v1，否则路径对不上，请求直接打 404。填完之后保存，桌面的模型下拉框里应该会多出一个名字，就是刚才填的模型名称。

如果 UI 里选不到，多半是下拉框需要手动刷新，或者直接重启一下桌面端。重启大法在工具接线这个场景里仍然是最实用的操作。

3.3 验证连通性并切换模型

配置好之后，进入验证环节。打开一个新的会话窗口，在模型选择器里切到新挂上的自定义模型，然后随便问一句“请用一段话介绍你自己”。如果能收到完整回答，恭喜，链路已经通了。

但联通只是第一步，我建议立刻做两个小测试。

第一个是流式输出测试。CodeBuddy 默认开启流式输出，也就是一个字一个字往外蹦。如果本地服务没开流式响应，或者响应格式不标准，桌面端可能表现为“一直转圈不出字”，然后过一会儿才整段弹出来。遇到这种情况，去检查服务的流式开关，确保它对stream: true的请求返回的是text/event-stream格式的数据流。

第二个是上下文测试。连续追问几个问题，比如先问“我项目的后端接口是什么”，再问“我刚才说的接口路径里哪个参数是必填的”，看模型是否记得前文内容。如果答非所问，多半是上下文长度设置太短。把服务的ctx-size从 2048 调到 8192，再重测一遍，基本就能解决。

这两关过了，CodeBuddy 才算真正接上了自定义模型。接下来才是重头戏——把零散能力收拢成工作台。

4. 把散装工具收拢成 WorkBuddy：搭一个属于自己的 AI 工作台

模型接上了，CodeBuddy 能用自己家的模型了，但我很快就发现，这还远远不够。因为模型只是“脑子”，没有配套的工作流程和工具，它就只是个能聊天的窗口。于是我用 WorkBuddy 这套方案把常用任务固化下来：把提示词模板、常用脚本、固定工作流都收进一个目录，通过 CodeBuddy 的会话和少量外部命令串联起来。

4.1 工作台不是“换个模型”这么简单

我理解的“AI 工作台”，得同时满足三件事：模型可换、指令可复用、任务可固化。只换个模型，等于换了颗更强的心脏，但手脚还是散的。

举个例子，以前我在 CodeBuddy 里让 AI 做代码评审，每次都要手动描述一遍背景：“项目用某某框架、要求并发安全、输出按严重程度排序……”有了 WorkBuddy 之后，这个需求被固化成一套指令模板，我只需要在对话输入框里敲/review，CodeBuddy 就会自动加载对应模板，把当前项目的上下文一并带上，然后按规定的格式输出评审意见。

工作台的核心价值，就是把重复劳动压缩掉。这一步看似是“少打字”的便利，本质上是把个人经验沉淀成了可复用的资产。

我的 WorkBuddy 目录结构大概是这样的：

workbuddy/ ├── prompts/ │ ├── review.txt # 代码评审模板 │ ├── design.txt # 方案设计模板 │ ├── test.txt # 单元测试生成模板 │ └── explain.txt # 代码解释模板 ├── scripts/ │ ├── sync_context.sh # 拉取项目上下文脚本 │ └── run_tests.sh # 快速跑测试脚本 └── config/ ├── model.json # 模型参数配置 └── shortcuts.json # 快捷指令映射

这个结构很轻，但它把“临时提问”升级成了“标准作业程序”。

4.2 常用工作流如何固化到工作台

固定工作流最核心的一步，是写模板。模板写得好不好，直接决定工作台好不好用。我踩过几次坑之后总结出一个通用套路：一份好模板至少包含角色设定、任务约束、输出格式、质量底线四个部分。

以代码评审模板为例，我会这样写：

你是一位资深代码评审员。请对以下代码进行评审。评审时请遵循： 1. 先指出阻断性问题（会导致 bug 或安全风险的问题） 2. 再列出建议改进项（可维护性、性能、命名等） 3. 最后给一段总结评价 输出格式要求：用 Markdown 列表输出，每项注明严重程度：阻断/建议/可选。 只评审，不修改代码，也不输出完整重构版本。

这段模板写清楚之后，在 CodeBuddy 里配合/review指令使用。它输出的评审意见格式稳定、重点突出，不会再出现“帮你把代码重写一遍”这种越界操作。

我还在模板里留了可变的占位符，比如项目框架、代码片段位置，这样同一条指令在不同项目里都能复用。用熟之后你会发现，指令模板才是工作台最值钱的资产。

4.3 几个让我效率明显提升的组合

WorkBuddy 这套方案里，有几个组合是我实际用下来觉得特别顺的，写出来供参考。

第一个组合是“需求拆解 + 任务列表”。我接到一个模糊需求时，先让 CodeBuddy 按模板把需求拆成可执行的子任务，输出成清单，再配合脚本自动把这个清单写入本项目的待办文件。原先半小时才能理清的思路，现在几分钟就有雏形，修改成本也低。

第二个组合是“日志分析 + 归因总结”。崩了一个线上服务，把日志片段贴给 CodeBuddy，它按模板先描述异常栈再定位可能原因，还顺手给出验证步骤。这个组合的关键是模板里严格要求“区分事实与推测”，避免模型一本正经地胡说八道。

第三个组合是“测试用例生成 + 一键执行”。让模型按被测函数的边界条件生成用例，写进测试文件，然后我脚本里预置的run_tests.sh直接自动跑。跑完看结果，红了就让 CodeBuddy 看失败信息自己修，绿了就收工。这套组合帮我省掉了大量手工编写测试用例的时间。

这些组合看起来都不复杂，但组合在一起，就把 CodeBuddy 从一个问答窗口变成了一个带工作流引擎的个人工作台。

5. 常见问题与排查技巧实录

实操中几乎没有一次跑通的场景，我前前后后踩了不少坑。挑几个普遍性强的整理成速查表，再对几种典型症状展开说说。

5.1 连不上服务？八成是这三个原因

连接问题排在所有问题的第一位，我遇到过的无外乎三种。

第一种是地址写错，尤其是忘记加/v1后缀，或者把127.0.0.1写成了localhost（有些环境解析会出现 IPv6 优先导致连接被拒）。排查方式就是先用 curl 手动请求一遍，确认服务本身通，再去看桌面端的配置。

第二种是服务进程没拉起来。本地服务崩掉之后不会自己恢复，我有一次重启电脑忘了拉服务，CodeBuddy 连着报了几十分钟错才反应过来。排查方式是去后台看一眼进程是否活着，或者直接看端口有没有监听。

第三种是密钥/鉴权限制。某些本地服务框架默认开启 token 校验，桌面端没填对应密钥就会被拒。排查方式是先关闭鉴权测试，通了之后再决定要不要开启。

5.2 模型能响应但回答质量差？先别怪模型

能连上但回答质量差，很多人第一反应是“这模型不行”。我的排查经验是：先别急着怪模型，大概率是配置或提示词的问题。

最典型的是温度参数。默认情况下很多服务把temperature设在 0.8 左右，闲聊还行，但拿到代码任务上就灾难了——回答飘、格式乱、代码里凭空多出各种不存在的 API。我把 CodeBuddy 发往服务的请求参数就地改了默认温度，统一降到 0.3 以下，质量立刻稳定很多。

其次是上下文窗口设置太小。前面提到的 2048 上下文基本只够聊几句天，一旦涉及多文件对比或者长日志分析，对话就“失忆”。把ctx-size调到 8192 是很实用的起步值，显存够的话 16384 更从容。

最后还要检查模型量化。同系列模型 Q4 和 Q2 的产出差距非常明显，尤其是代码生成领域，低量化经常产生语法错误。有条件就至少上 Q4_K_M，不要为了省显存牺牲这一档质量。

5.3 桌面端卡顿与资源占用的排查经验

本地模型跑在同一个机器上，桌面端卡顿有时候不是模型的问题，而是资源竞争。

我的排查顺序是这样：先看显存占用，再 CPU 和内存占用，最后判断是推理进程吃资源还是桌面端本身卡。

如果推理进程把显存吃满了，桌面端做任何操作都会被拖慢。解决办法是缩小上下文长度，或者关掉几个不用的进程。如果推理时 CPU 持续满载，说明手头模型对当前 CPU 压力偏大，要么减少并发请求，要么换个更小的模型。还有一种容易被忽略的情况：磁盘 IO。模型文件如果放在机械硬盘上，启动加载和上下文换入换出都会非常慢，换到 NVMe 固态上能明显改善响应速度。

我最终的资源分配方案是：给服务进程限制最多 20G 显存，上下文 8192，让 CodeBuddy 桌面端独占剩余资源，运行起来非常稳。

6. 实测心得：这套方案后续还能怎么扩展

聊几个我实际用下来的心得，还有后续打算扩展的方向。

第一点心得是，接自定义模型不是一次性的活儿，而是一个长期迭代的过程。模型更新很快，今天觉得好用的模型，下个月可能就有新版本；一段时间不维护工作台的模板，写出来的评审意见又会退化。WorkBuddy 这套方案最值得投入精力的地方，其实是把提示词模板维护好、把工作流固化好，模型反而可以随时换。

第二点心得是，本地模型和云模型各有用武之地，没必要二选一。我现在保留了两个入口：CodeBuddy 默认连本地模型用于日常开发和评审，遇到特别烧脑的高难度推理任务，临时切回云端旗舰模型。两条链路并存，让我既保底又够强。

后续的扩展方向，我目前有两个想法。一个是给 WorkBuddy 加一层“会话记忆”，把常用的项目背景自动注入到每次会话开头，省去每次重复交代的麻烦。实现思路是在sync_context.sh里动态生成一段项目摘要文本，作为模板的前置内容。另一个方向是把 CodeBuddy 的对话记录自动存档、按月归档，让它成为一个可检索的“开发决策日志”。这样既能追溯当时为什么这么设计，也能训练自己日后的提示词模板。

给 CodeBuddy 接自定义模型这件事，本质上是在找回工具的掌控感——让它按我的习惯工作，而不是我去适应它的规则。整个过程没有特别高深的技术，但每一步的配置和取舍都能带来实打实的效率提升。如果你也想给手头的桌面端工具换一颗“自己说了算”的脑子，希望这篇实战记录能让你少走一些我走过的弯路。