本文非 AI 创作

前言

现在网络上的文章都没人看，是因为很多内容不是人写的。
在网上找参考资料的时候我就发现大量的解析源码的文章全部都是 AI 写的，条条是到，然后观看量几乎没有，人一看到 1、2、3 这样的列举就头疼，现在在这样的时代下，坚持手动创作其实确实挺需要毅力的。
本文主要是我在浏览和思考的过程中，总结的一些我自己在没有看之前想不到的地方。

循环本身

首先循环如果真的简单说非常简单，其本质是工具的调用。为什么之前的模型只会对话？而现在加了 cc 之后就能工作了，答案就是工具。有了工具就有了手，就能干活了。而整个循环就是不断的在调用工具，直到不需要调用工具为止，工作就结束了。这个设计就像是人在写代码一样，人是先思考，然后再开始写，然后测试，发现不行回来再改再写，再测试再写，最终写完。AI 也是，思考要怎么做，使用哪些工具去做，做完之后要怎么检查等等。最终全部做完，不需要用工具了，只剩下思考总结一下就退出了。

所以 agentic loop 其实说简单就是这样而已。而其中更细节的更难的，其实是工具的调用和执行。

多 agent 的好处

如果让你直接想为什么需要多 agent 同时执行，你没有思考直接给到的想法肯定就一个字 “快”。但是除了快，还有别的什么吗？

我看了解析给我有几个印象深刻的地方：

1. 每个 agent 的工具不同，效率就能不一样。因为我们直到工具和 mcp 越多，越慢，因为 AI 要做出更多的选择，而由于多 agent 协同工作，每个都负责一定的“螺丝钉”的工作，就不需要那么多工具了，比如你只是单纯写代码，就不用联网去搜了，调研的交给别人去完成了。
2. 上下文，这个仔细自己想一下还是能想到的，因为上下文现在是有限制的，上下文太大会被压缩，而分给其他 agent 工作之后，细节就不需要管了，我不需要知道这个工作是如何完成的，我只要知道最后已经完成就可以了。最后做一个汇总就好了。
3. 将通知作为用户消息。多 agent 协作是通过消息机制来沟通的，而对于大模型来说，并不用理解这种消息机制，而将其他 agent 派来的任务直接作为用户的一种行为输入就可以了，将机器命令作为人的命令去执行。这样也是完美覆盖了之前的循环的。

整体实现其实并没有复杂，用的还是那些技术，甚至可以说，这样的协同工作和消息机制我好像在哪里看到过，没错，操作系统里面。

为什么 Claude code 看起来更智能

至少从我使用角度上来说，即使使用相同的模型的情况下 cc 比其他 agent 会更智能。我也看到了其他对于 cc 和 oc(openclaw) 的讨论，包括论文，其实我觉得他们本质没什么不一样。

我的总结是：通过提供工具和调用链将 LLM 和目标结合为 flow 从而实现用户描述的任务。

而区别就在与权限的控制、工具的提供、上下文的提供的等等其他方面。

那么为什么看起来完成任务的效果更好呢？我觉得其中很大一部分原因在于，用更少的上下文和更少的工具完成任务，有时候质量反而会更高。有的时候我觉得过多的 harness 就是跑非的关键，带上了一堆和任务无关的上下文就会影响它的工作效率和状态，而带上了一堆无用的工具就像是累赘让 AI 选择困难。

思考

对我们使用上来说有什么帮助吗？其实几乎没有，我一直相信好的 AI 工具是不需要人过多去介入和使用的，而看完之后给我更多的是对于 agent 设计的思考。

如果现在让我去设计一个新的 agent，抛开 agnet loop 的想法，获取我会用两个系统，一个是有限状态机将工作分成几个形态 agent 在这几个形态中运转，一个是事件总线所有的消息包括用户全部通过统一调度去分发，但依旧没有 AL 来的那么简单直接和优雅。

所以其实我们在设计 agent 的时候，如何让它更简单直接的去完成用户的任务，而不是让它去思考和选择太多的工具和上下文，才是我们应该去思考的。

参考链接

• https://code.claude.com/docs/en/agent-sdk/agent-loop
• https://arxiv.org/pdf/2604.14228
• https://mp.weixin.qq.com/s?__biz=MzUxODAzNDg4NQ==&mid=2247557309&idx=1&sn=db872d9df4336797d2c364b5c4e4e880

2025 年度读书总结

读书列表

仅罗列，顺序是随机。怕链接会过期，失效的建议直接搜书名。

非小说

• 《架构整洁之道》
• 《创造 : 用非传统方式做有价值的事》
• 《深入理解 Linux 进程与内存》
• 《卓有成效的管理者》
• 《System Design Interview, Vol.2》
• 《贝佐斯如何开会》
• 《如何阅读一本书》
• 《微习惯》
• 《非暴力沟通》
• 《从零开始的大语言模型原理与实践教程》
• 《StatQuest 图解机器学习》
• 《第五项修炼》
• 《黄仁勋：英伟达之芯》
• 《时势》
• 《财富方程式》

小说

• 《白夜追凶》
• 《凶案密码》
• 《夜行实录》
• 《天才在左，疯子在右》
• 《漂白》
• 《破绽》
• 《尸案调查科》

2025 最佳

《贝佐斯如何开会》

今年毫无疑问是这本书，因为这本书是真正付出实践的一本书。其中的给我影响的就是，选择什么要开的会，哪些会议是应该开的，哪些是不应该开的。然后就是 1 张纸的会议，将会议的内容浓缩到一张纸中，开会之前阅读。实际操作下来极大的提升了会议的效率。里面的内容让我去实际中可以运用和体验到改变，这本书就变得非常有意义了。

新的思考

今年由于 AI 的工具出现的可太多了，很多时候都在尝试各种工具所带来的改变，其实看的视频和其他内容比书要多不少。也造成了不少新的思考。有人问我，现在看书还有用吗？我的回答是一定的，看书仅仅是你的其中一种输入方式而已，现在有了那么多工具也就有了更多的更好的输入方式，但是“潜移默化”四个字我是一直相信的，很多你觉得很有道理的短视频或者 AI 的解释图片非常精美，但是可能你转头就忘记了，但是我看的很多书带给我的思考依然我还记忆犹新。
当然我看的书明年可能也会发生很大的变化，因为发现很多的基础亦或者底层原理的书要被我扔了，比如我现在就有几个 Rust 的语法书已经扔了。简单点说就是 “八股文” 的时代终于要结束了，我以前看的 Spring 源码都可以扔了，因为确实不会用了。而你留下的是什么呢？是其中的设计思想。
所以这也对于我后续的博客产生了一些变化，我可能会更少写一些教程或源码解析的类的博客了，会更多的关注一些设计、思路以及对于一些常见问题的解决方案，在现在这个时代下，我觉得设计是将会是后续的好路。如何针对一个场景给出自己的设计，如何快速评判 AI 给出的几个设计方案应用在现有场景的可行性。

总之，希望在新的一年里面，能找到属于自己的新的节奏和思路，把握这个美好的时代带给我们的风。

本地的设计来自于群里的一个小伙伴的提问：

A: 请教一下，关于软删除，删除后新增同样的数据报 UNIQUE 索引冲突的问题，大家有没有什么好办法处理？
B: 重建唯一索引，原来字段和软删除时间戳或状态建立唯一索引
A: 恩，目前就是这样做的，看来只能重建索引了

看到这个报错，“老司机”应该会心一笑，因为有这部分开发经验的同学应该经常遇到这个问题，而我对于上面 B 提到的使用 原字段 和 状态 建立唯一索引的方法更是觉得不妥，这几乎是每一位后端开发者在进阶路上都会踩到的坑——软删除（Soft Delete）与唯一索引（Unique Index）的冲突。

在现代 Web 开发中，为了数据安全、审计追踪以及防止手误，我们很少直接从数据库中 DELETE 物理删除数据，而是习惯使用一个标记位（如 is_deleted）来做“软删除”。然而，当业务需求遇上“用户名全局唯一”、“手机号全局唯一”这类硬性指标时，软删除和数据库层面的唯一约束就会发生剧烈的化学反应。

今天，我们就来聊聊这个经典话题：在软删除模式下，如何优雅地设计唯一索引？

软删除状态标记会出现什么问题？

下面均以 username 作为唯一字段

首先，如果单独给 username加唯一索引肯定不行，因为软删除的情况下，用户名还在，如果删除的用户名再次添加，就会报错。可能会出现后台查不到，用户也用不了的情况。既然单纯索引 username 不行，那把删除状态也加进去呢？

• 做法：建立联合索引 UNIQUE KEY (username, is_deleted)。
• 结果：
  • ('Alice', 0) 和 ('Alice', 1) 可以共存。看似解决了问题。
• 致命缺陷：
  • 如果 Alice 注销（变成 1），重新注册（变成 0），再次注销（变成 1）……
  • 第二次注销时，数据库里将会有两条 ('Alice', 1)。
  • 报错！ 唯一索引再次生效。这意味着一个用户名只能被“软删除”一次。这显然不符合现实业务需求。

时间戳

然后就有人会很容易想到使用时间作为删除的标记，那么因为每次删除的时间大概率不一样，所以使用删除时间和用户名作为联合唯一索引的话就能解决这个问题。不过坑点也有，那就是 delete_at 初始值不能设置为 NULL，因为 MySQL 对于带有 NULL 值的联合索引是有特别处理的，在 5.7 里面两个相同用户名均为 NULL 删除时间的情况是允许存在的。这也是为什么想要写这篇博客最大的原因，因为这个 bug 可能存在但可能一直不会被发现。而且我还遇到过，因为数据库的限制往往是最后一道防线，是为了避免并发条件下不会出现脏数据而设计的。而前置业务代码中肯定也会做用户名唯一性的校验和判断，所以大多数情况下会测不到，特别是注册还需要验证什么的。只有大量并发的时候才会出现。

• 做法：
  • 字段改为 delete_at (建议用 BigInt)。
  • 未删除：默认为 0（这也是关键点，尽量避免使用 NULL）。
  • 已删除：填入当前的毫秒级时间戳。
  • 索引：UNIQUE KEY (username, delete_at)。
• 演练：
  1. Alice 注册：('Alice', 0)。 -> 成功
  2. Alice 注销：更新为 ('Alice', 1678888888)。 -> 成功
  3. Alice 重新注册：插入 ('Alice', 0)。 -> 成功（因为 0 != 1678888888）
  4. Alice 再次注销：更新为 ('Alice', 1679999999)。 -> 成功（时间戳不同）
• 评价：简单、有效、能保留完整的删除历史。适合绝大多数业务场景。

归档表

当数据量极大，或者“历史数据”完全不需要参与日常业务查询时，物理隔离也是一种的选择。我曾经就也遇到过这样的情况，然后后续发现业务调整这部分的删除数据直接转移到另一张归档表中，一方面这部分数据可以被直接减少，极大的可以减轻主表的压力，而且这部分的归档数据往往只有在特殊情况下才会被审计，通常情况下可能永远就用不到了。

• 做法：
  • users 表：只存活跃用户。直接加 UNIQUE KEY (username)。
  • users_history 表：存删除的用户，不加唯一约束。
  • 删除动作（只是做一个样例，实际可能是在业务代码中实现的）：

    1 2 3 4

    START TRANSACTION; INSERT INTO users_history SELECT * FROM users WHERE id = 1; DELETE FROM users WHERE id = 1; COMMIT;

• 评价：主表极度瘦身，查询飞快。但代价是“删除”操作变重了，且如果要恢复数据（Undo），逻辑会比较麻烦。（当前这种恢复操作可能这辈子出现不了一次）

修改唯一字段

其实还有一种业务上也会用到的方法，那就是直接修改唯一字段，让唯一字段永远唯一。比如删除的时候，在软删除的基础之上，直接修改用户名，在用户名后面拼接上一个时间戳，这样也可以保证用户名的唯一，不过这也是建立在以后不需要查询删除和恢复数据的基础上。因为处理简单，所以也会被使用到。只要业务上允许就可以。

总结

之前我也会觉得一个软删除能有什么？但是实际中其实这种小的坑还是特别多的。而且特别是在国内的环境上，要求每个数据不能被永久删除，万一审计亦或是安全审查核对的时候，还有可能是排查意外问题等等情况下，所以在软删除被更多用到的时候，这样的问题就会容易出现。而正因为有朋友在群里面问了，我就发现这种坑特别容易坑到人。当然解决方案多种多样，我们只要选择自己合适的就好。

如果你正在使用 Watchtower 来自动更新 Docker 容器，并使用 Amazon ECR (Elastic Container Registry) 作为你的私有镜像仓库，你可能会遇到一个棘手的问题：no basic auth credentials. Proceeding to next.

ECR 的身份验证机制是动态的，依赖于临时的 AWS 凭证，而不是静态的用户名和密码，所以需要一些额外的配置来帮助我们解决拉取 ECR 中镜像的问题。通过使用 amazon-ecr-credential-helper（一个 Docker 凭证助手）来解决这个问题。

解决方案概览

整体的解决方案其实官方在文档中已经给出，https://containrrr.dev/watchtower/private-registries/#credential_helpers

不过由于文档比较旧了，其中有一些部分需要调整一下。整体的策略是构建 amazon-ecr-credential-helper 二进制文件，将其存储在一个 Docker 卷（Volume）中，然后配置 Watchtower 容器来使用这个助手和相应的 Docker 配置文件。

步骤一：构建凭证助手 (Credential Helper)

首先，我们需要编译这个助手。我们不会将它安装在主机上，而是使用一个临时的 Docker 容器来构建它，并将结果输出到一个共享卷中。

创建 Dockerfile

创建一个名为 Dockerfile 的文件，内容如下

1
2
3
4
5
6
7

FROM golang:1.24

ENV CGO_ENABLED=0

RUN go install github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login@latest

WORKDIR /go/bin/

注意这里的内容就和官方的不一样，官方的镜像版本太老，导致无法正确安装

构建并将二进制文件存入卷

运行以下命令来创建卷、构建镜像，并运行一个临时容器将编译好的 docker-credential-ecr-login 二进制文件复制到卷中：

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 创建一个用于存储二进制文件的卷
$ docker volume create helper

# 2. 使用上面的 Dockerfile 构建镜像
$ docker build -t aws-ecr-dock-cred-helper .

# 3. 运行容器，将 /go/bin (包含二进制文件) 挂载到 helper 卷
# 容器启动后即退出，但二进制文件已保存在卷中
$ docker run  -d --rm --name aws-cred-helper --volume helper:/go/bin aws-ecr-dock-cred-helper

# 4. 然后查看是否存在 helper，如果存在就表示已经可以了
$ docker volume ls

步骤二：配置 Docker 凭证

在你的工作目录（例如与 docker-compose.yml 同级）创建一个 .docker/config.json 文件。

注意：请将 <AWS_ACCOUNT_ID> 和 <AWS_ECR_REGION> 替换为你的实际 AWS 账户 ID 和 ECR 区域。

1
2
3
4
5
6
7
8
9
10
11
12

{
    "credsStore" : "ecr-login",
    "HttpHeaders" : {
       "User-Agent" : "Docker-Client/19.03.1 (XXXXXX)"
    },
    "auths" : {
       "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_ECR_REGION>.amazonaws.com" : {}
    },
    "credHelpers": {
       "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_ECR_REGION>.amazonaws.com" : "ecr-login"
    }
}

步骤三：配置 Watchtower (Docker Compose)

现在我们将所有部分组合在一起。创建一个 docker-compose.yml 文件来启动 Watchtower。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

services:
  myapp:
    image: 1651561651.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
    container_name: myapp
    restart: unless-stopped
    # 通过配置 label 能告诉 watchtower 需要关注哪些镜像的更新
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config.json:/config.json
      - helper:/go/bin
    environment:
      - HOME=/
      - PATH=$PATH:/go/bin
      - WATCHTOWER_POLL_INTERVAL=10 # 间隔时间 10s 用于测试，实际可以根据所需调整
      - WATCHTOWER_MONITOR_ONLY=true
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_CLEANUP=true
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=AKxxxxx
      - AWS_SECRET_ACCESS_KEY=xxxxx

# 最重要的是这个，需要将我们之前的 helper 挂载进去
volumes:
  helper:
    external: true

然后，你就可以进行测试了，启动后可以查看 watchtower 的日志可以看到是否已经能正常的拉取镜像，而没有出现认证的错误了。

需要注意的是，在实际的测试过程中发现有时候第一次部署的时候如果没有按照部署的步骤来操作，如果先部署了 watchtower 然后再重新挂载的镜像，一定要注意先删除实例 (docker compose down)，以及清空 helper docker volume rm -f helper 然后重新执行步骤，从而能避免无法正确挂载或正常执行的问题。

总结

通过构建 amazon-ecr-credential-helper 并将其与 Watchtower 容器共享（通过 Docker 卷），同时提供正确的 Docker 配置文件和 AWS 环境变量，我们就设置了一个安全且自动化的流程。现在，Watchtower 可以监控你的 ECR 仓库，并在新镜像发布时自动更新你的服务。

在现代 Web 应用中，拖放排序功能为用户提供了直观、便捷的交互体验。无论是调整任务列表的优先级，还是重新排列相册中的图片，流畅的拖放操作总能极大地提升用户满意度。然而，一个看似简单的功能，其背后却需要一个高效、稳健的后端设计来支撑。

思考

在我最早写代码的时候，那个时候还没有那么流行 H5 前端技术也没有现在迭代那么好，拖动排序也还不流行，那个时候的排序是分为：上移、下移、置顶、置底这些操作。所以在那个时候，并没有什么问题，你只需要一个 order 值记录数据的顺序位置，并在点击按钮的时候执行对应操作进行整体排序亦或是简单的数据修改就可以了。比如：上移其实就是和前一条数据交换 order 值罢了。

随之技术发展，到了现在，拖动变成了一个非常容易实现的操作，从而问题就出现了。如何让一个数据放到任意一个位置呢？

方案

笨办法

当年我的第一个方案就是前端传递这个数据的最终位置信息，比如将 A 移动到，2 和 3 数据之间。然后后端收到这个数据重新计算所有数据的 order 并更新。

1

{"id": 100001, "pre_order": 2, "post_order": 3}

这就和一个数组排序一样，将一个数据找到起点或终点，然后定位到所需位置，然后将之后的数据全部重新计算一次 index 索引之后重新得到新的顺序，这个方案可能是最直接能被想到的。可以简单叫 ”更新法“

到现在回想起来，其实我觉得这种方案在大多数情况下依旧是可用的，为什么？因为绝大多数需要进行拖动排序的场景不会有太大的数据量。仔细思考 🤔，如果你有一千条数据，你是不可能期望用户将一条数据从第一拖动到 500 的，这操作太麻烦了。多数场景下几十条数据之内是会采用这种交互的，而这个方案最大的问题就是可能一次性更新的记录数太多。不过也正由于场景中数据量不会太大，所以没什么问题。

但如果真的数据量比较多，又有调整顺序的需求呢？即便不是拖动的交互。

新办法

为了解决全量更新法的性能问题，我们可以采用一种更为精妙的方法——取中值法。这种方法的核心思想是，为每个列表项分配一个排序值（可以是浮点数或一个很大的整数），当一个项目被移动到新的位置时，它的排序值将被设置为其前后两个项目排序值的中间值。

实现逻辑

我们同样需要一个排序字段，例如 sort_key，但这次它的类型通常是浮点数（float 或 double）或长整型（bigint）。为了避免一开始就出现小数，可以初始化时使用较大的整数间隔，例如 10000, 20000, 30000…

1

{"id": 100001, "pre_id": 100002, "post_id": 100005}

通过 pre_id 和 post_id 找到 prev_sort_key next_sort_key，然后计算这两个值的中间值：new_sort_key = (prev_sort_key + next_sort_key) / 2。

让我们直接看表格数据变化会更容易理解，下面展示的是任务 D 移动到 任务 A 和任务 B 之间的情况：

特殊情况

这个方案也有几个特殊情况需要处理

• 移动到首位：如果项目被移动到列表的最前面，其新的 sort_key 可以是当前最小 sort_key 的一半，或者 min_sort_key - 10000（如果使用整数间隔）。
• 移动到末尾：如果被移动到最后，其新的 sort_key 可以是当前最大 sort_key 再加上一个固定间隔，例如 max_sort_key + 10000。
• 精度问题：如果频繁地在两个元素之间插入新元素，sort_key 的浮点数精度可能会耗尽，或者整数间隔会变得非常小。此时，需要一个“重排（rebalancing）”机制，当检测到排序间隔过小时，异步地重新计算并均匀分布整个列表的 sort_key 值。

对于精度问题这通常是一个兜底的方案，实际中很少情况会出现经常拖动到同一个位置的情况，并且如果选择间隔为 65536 是能支持拖 16 次…

优点

这个方案的优点非常明显，就是拖动完成之后只需要更新一条数据就可以完成想要的排序操作，避免的频繁更新大量数据的问题，同时这个方案的实现代码会更简单，只需要简单的查询和计算即可，并且可以将两种特殊情况放入到基础情况中一并计算，代码会更加简洁。

总结

当然选择哪种拖动排序的设计方案，最终取决于您的具体业务需求。

• 如果您的应用场景中列表规模可控，且用户不会进行过于频繁的排序操作，更新法以其简单性和可靠性成为一个不错的选择。
• 而对于追求极致性能和流畅用户体验的大型应用，取中值法无疑是更优的方案。虽然实现上稍显复杂，但它带来的性能提升和可扩展性是全量更新法无法比拟的。

这作为第一篇，也就是我最想写的一篇，我的感觉是，如果我从没有听说过这个方案，那么我可能从工作开始到结束会一直用老办法用到底。我也是偶然在知乎上看到别人发帖才去仔细思考这个场景和他们提出的设计，最后用在了实际业务中发现确实好用。一旦你听过这个设计，那么会让系统的某个小部分更优雅，也正是这一个个小场景中的小设计其实是最容易被学会的。这种经验我觉得会比我们常说的系统设计来的更有意义。

参考链接

• https://www.zhihu.com/question/55789722
• https://gist.github.com/wonderbeyond/0516ed0ec5da78a40fbccf86149c229d
• https://cloud.tencent.com/developer/article/2436900

工厂模式（Factory Pattern）是设计模式中最常见、最基础的模式之一。往往在初学设计模式时，工厂模式是第一个接触到的模式。但在实际工作中，很多人对工厂模式的理解都停留在“有一个工厂类负责创建对象”这样的表面现象上，导致在使用时往往走入误区。

在实际工作之后慢慢积累经验，我发现工厂模式的本质其实并不在于“工厂”这个名字，所以我想带你重新思考一下设计模式的本质。

工厂实现

为了说明工厂模式的本质，我们先来看一个简单的代码例子

比如，我们有一个“支付”场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

package main

import (
"fmt"
)

// 1. 支付器接口 (产品的抽象)
type IPayment interface {
Pay(amount float64) string
}

// 2. 具体产品A：支付宝
type AliPay struct{}

func (a *AliPay) Pay(amount float64) string {
return fmt.Sprintf("使用支付宝支付了 %.2f 元", amount)
}

// 3. 具体产品B：微信支付
type WechatPay struct{}

func (w *WechatPay) Pay(amount float64) string {
return fmt.Sprintf("使用微信支付了 %.2f 元", amount)
}

// 4. “工厂”函数
// 它根据输入，决定“new”哪个具体的结构体
func NewPayment(payType string) (IPayment, error) {
switch payType {
case "ali":
return &AliPay{}, nil
case "wechat":
return &WechatPay{}, nil
default:
return nil, fmt.Errorf("不支持的支付方式: %s", payType)
}
}

// 5. 客户 (调用方)
func main() {
// 客户代码完全不认识 AliPay 或 WechatPay 结构体
// 它只认识 "IPayment" 接口和 "NewPayment" 工厂
payment, err := NewPayment("ali")
if err != nil {
fmt.Println(err)
return
}
fmt.Println(payment.Pay(100.0))

payment, err = NewPayment("wechat")
if err != nil {
fmt.Println(err)
return
}
fmt.Println(payment.Pay(200.0))
}

灵魂拷问：为什么要这么做？

上面的代码，main 函数（客户）里为什么不直接这样写？

1
2
3

// 客户直接 "new"
payment := &AliPay{}
fmt.Println(payment.Pay(100.0))

这样不是更简单吗？为什么非要搞一个 NewPayment 函数绕一下？

答案是：为了“隔离”。

main 函数是“使用”支付功能的地方，而 AliPay{} 和 WechatPay{} 是“实现”支付功能的地方。

在没有工厂的情况下，“使用者”main 强依赖于“实现者”AliPay。

• 如果 AliPay 的创建方式变了（比如 NewAliPay(config)），main 函数就必须修改。
• 如果 main 函数想换成 WechatPay，main 函数也必须修改。

而 NewPayment 函数，就是那个“隔离层”。

使用工厂的好处是：
“使用者”（main）和“具体实现”（AliPay）解耦了。
main 只依赖“抽象”的 IPayment 接口和“工厂” NewPayment。

至于 NewPayment 内部是用 switch 还是 if，是返回 &AliPay{} 还是 &AliPay{config: ...}，main 根本不关心。

这，就是“抽象实现细节”的第一层。

一个不叫“工厂”的实现

NewPayment 函数虽然好，但它有个致命缺陷：违反了“开闭原则”。

如果我们要增加一种“银联支付”（UnionPay），我们必须去修改 NewPayment 函数的 switch 逻辑。

这在大型项目中往往会变得更加麻烦。我们希望的是，增加新功能时，不修改老代码。

我们来看一个在 Go 中更常见、更优雅的实现方式 —— “注册”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

package main

import (
"fmt"
)

// --- 支付接口和具体实现 (这部分不变) ---
type IPayment interface {
Pay(amount float64) string
}
type AliPay struct{}
func (a *AliPay) Pay(amount float64) string { /* ... */ return "支付宝支付" }
type WechatPay struct{}
func (w *WechatPay) Pay(amount float64) string { /* ... */ return "微信支付" }

// --- 我们不再叫 "Factory" ---

// 1. 定义一个“创建者”的函数原型
type PaymentCreator func() IPayment

// 2. 一个全局的“注册表”
var paymentRegistry = make(map[string]PaymentCreator)

// 3. 注册函数：允许外部注册新的支付方式
func RegisterPayment(payType string, creator PaymentCreator) {
if _, ok := paymentRegistry[payType]; ok {
// 警告：重复注册
}
paymentRegistry[payType] = creator
}

// 4. 获取函数：从注册表中获取实例
// 这个函数就是我们新的“工厂”，但它不叫“工厂”
func GetPayment(payType string) (IPayment, error) {
creator, ok := paymentRegistry[payType]
if !ok {
return nil, fmt.Errorf("不支持的支付方式: %s", payType)
}
// "创建" 的动作在这里发生
return creator(), nil
}

// --- 在不同的包中初始化 (模拟插件化) ---
// (在实际项目中，这会在 ali_pay.go 和 wechat_pay.go 的 init() 中完成)
func init() {
RegisterPayment("ali", func() IPayment { return &AliPay{} })
RegisterPayment("wechat", func() IPayment { return &WechatPay{} })
}

// --- 客户代码 ---
func main() {
// 客户现在只依赖 GetPayment
payment, err := GetPayment("ali")
if err != nil {
fmt.Println(err)
return
}
fmt.Println(payment.Pay(100.0))

// 思考：如果我们想增加“银联支付”？
// 我们只需要新建 union_pay.go，并在其 init() 中调用 RegisterPayment
// GetPayment 和 main 函数完全不需要改动！
}

这个实现是不是很眼熟？

Go语言标准库 database/sql 就是这么干的。

• sql.Register(driverName string, driver driver.Driver)
• sql.Open(driverName string, dataSourceName string)

sql.Open 就是那个“工厂”函数，它根本不知道有哪些数据库驱动（MySQL, PostgreSQL…），它只管去注册表里查 driverName。而各个驱动包通过 init() 函数把自己注册进去。

注意并不是所有的情况都适合使用 init 方法去隐式注册（有的人不喜欢），那么显示注册也是可以的，只要能达到“使用者”和“实现者”解耦的目的即可。

我不叫“工厂”，就不是工厂了吗？

现在，我们有了两个实现：

1. NewPayment：一个巨大的 switch，它知道所有具体实现。
2. GetPayment：一个 map 和一个查找函数，它不知道任何具体实现，它只知道一个“注册表”。

哪个是“工厂模式”？

答案是：它们都是。

NewPayment 是一个“集中式”的工厂。
GetPayment (以及 RegisterPayment) 是一个“注册式”的工厂。

这引出了我们最终的结论：

工厂模式的本质，不是那个叫 Factory 的类或那个叫 NewXxx 的函数。

工厂模式的本质是：将“创建对象的具体过程”从“使用对象的地方”中剥离出来。

它是一种抽象。

它在“使用者”（如 main 函数）和“实现者”（如 AliPay 结构体）之间，建立了一个隔离层

至于是用 switch（简单工厂）、用“接口+实现”（工厂方法）、用“接口返回接口”（抽象工厂），还是用 map（注册器）来实现的……

这都不重要。

这些只是“术”（实现方式），而“道”（本质）是抽象和隔离。

所以，下次当你在代码里看到一个“注册中心”（Registry）、一个“提供者”（Provider）、一个“管理器”（Manager）或一个“服务定位器”（Service Locator）时，如果它的核心职责是根据某些条件创建并返回一个抽象接口的实例，那么，它就是工厂模式。

它叫不叫“工厂”，真的无所谓。

总结

其实再说的直白一点，只要你抽象了实现细节，让使用者不需要关心具体实现类的创建过程，就是在使用工厂模式了。而“工厂”只是说你抽象之后是一个创建“产品”的说法而已。

所以，工厂模式的核心思想是抽象实现细节，而这个思想是让你的代码更加解耦和灵活的方法之一。也是程序设计中非常重要的一个原则。

在实际中我做过大量的 Code Review 其实都是在做抽象这一件事，这个优化真的很重要，所以希望通过这篇文章能让你对工厂模式有一个新的认识。

前言

首先作为一个技术人，我听过很多的技术分享和大会，也都是那种非常干货的分享，源码分析、架构场景、技术原理等等，而这次 Meetup 显然不是技术人的盛会而更多的 AI 的一瞥。

分享要点

我记录了下面几点在分享中让我感受很深的部分：

• 一个 14 岁少年手挫 AI Co-Founder，第一个演讲的就是这个主题，先不说做的怎么样，真切的让我体会到了 AI 就是让编程直接 0 门槛，那么未来你的优势是什么？
• Cursor Engineer 连线提到，内部 100% Cursor，也就是 Cursor 自举，自己写自己。
• Cursor 比起直接生成 PPT 不如直接生成 HTML 来得更实在。 这个可以理解，毕竟我相信 PPT 的训练数据远不如代码的训练数据来的更多，而且现场的演讲者的 PPT 就是通过 AI 做的 HTML。
• 如何描述一个我无法准确描述的内容？ 当我们使用 AI 的时候，很多时候会遇到两个问题，一个是我们就不知道要做出什么样，还有一个就是我不知道我该如何表达。其实很简单，在前面多加一步，先让 AI 先拆解这个问题，让它向你询问并获取信息。
• AI 如何写脱口秀？ 当 AI 遇到生活化的场景时，往往描述让人觉得很奇怪，因为它是没有感知的，于是写的脱口秀就不好笑。怎么解决呢？我们可以将这样的感知场景和数据给他让他上下文从而的输出更生活化。
• 如果 Agent 足够强大，人做什么？ 提出好的需求+培养审美+领导力。

我的思考

立刻 Coding？

程序员做产品最容易犯的错误是，有了想法，立刻编码。而到了 AI 时代，编码的试错成本变得很低，就导致这个错误依旧在延续。快速做出 Demo 试错本身没有问题，但是我认为，更好的方式还是在给 AI 之前，先问问自己或问问 AI 你的需求是什么，准备如何去做，可能有哪些问题，而不是直接 Coding 然后再改。因为现在 AI 修改很容易造成屎山代码。

文档记录好帮手

AI 由于现在上下文的关系，很容易忘记项目之前出现过的一些问题和要求，而如果有一个 Project recording 去记录你做的重要更改和需求，那么每次只需要告诉 AI 你可以先查看之前的项目记录，遵守之前的约定和改动，这些记录就能更好的帮助它完成任务。

根据效果重构提示词

如果你不知道如何写，或者写不好提示词，那么请先保存现在的项目情况，然后直接随便写，然后看效果，看完效果不对之后，不是立刻让 AI 修改，有时候可能需要直接先回滚代码，然后重构你的提示词，补充你认为前一次做的不对的地方，然后再看效果，这样会比有时候的直接修改来的更靠谱。

你是喜欢写代码吗？

在没有 AI 之前，你如果问我这个问题，我毫无疑问会说是。我当然是喜欢写代码的。而有了 AI 之后，我发现其实我最终并不是喜欢写代码，而是喜欢创造或利用编程去改变生活，无论是自己的生活还是别人的生活。 编码是我觉得能做出自己想要的东西，现在可以变成了我直接能让 AI 给我想要的东西了。所以或许我们是时候做出改变了。

总结

AI 让我们回到最开始的样子，让我们更专注于用户最终的需求本身，而不是无脑的技术堆砌。

我平常会更喜欢写技术类型的博客，其实很少写思考类型的博客，这一次本来我是已经写了几篇博客：

• 结合 RAG 构建你的知识库
• 利用 transformers LoRA 微调模型
• 训练属于你自己的 AI 问答模型

写完这些之后，说实话，我有点意兴阑珊。不是因为技术不酷，相反，这些 AI 强大得令人兴奋。然后我发现这些内容好像少了点灵魂，而且网上的教程已经足够多了，特别是视频，一步步教你微调，比我的肯定要详细，于是思考了一下，重新构思才有了今天这篇文章。相比手把手教你敲代码、调参数，我更想聊聊这段时间在尝试“结合 AI 开发应用”过程中一些感悟。这更像是一场自我反思，也希望能引发一些同路人的共鸣。

结合的方式

首先来说说结合 AI 开发应用的方式，实际中当然有很多，我总结分类一下为：

• 直接利用 AI 对话能力
• RAG
• 微调
• MCP/Agent

所以我将从这几个分类聊聊尝试过后给我的感受。

直接利用 AI 对话能力

这是最直接、门槛最低的方式。开发者通过设计精心构造的提示词（Prompt），调用大型语言模型提供的对话/补全 API，让模型根据输入生成文本输出。我试过的几个场景是：

• 问答
• 摘要
• 翻译

都很不错，接入方便好用，大家也都知道，而这里结合和能否成功的关键在于 产品化。因为这个门槛最低，你的产品交互能否让用户感觉丝滑特别重要。

我的总结思考是：让普通人跳过和 AI 对话的步骤，直接得到想要的结果（路径缩短），这是这类产品的目标。

当然它的缺点是不够专业（我叫作知识局限性），毕竟它得到的数据都是公开的，对于它从来不知道的事情来说，它也 无能为力。那么就需要下面的技术了。

RAG

从你提供的个人数据库中检索出最相关的信息片段。然后将原始问题 + 检索到的相关上下文一起打包成一个新的 Prompt，发送给 AI 生成最终答案。

这里的检索往往都会采用向量的方式，之前我也写过向量数据库相关的文章，有的时候检索结果并不尽人意（不过我也没优化过）。

而其实尝试过 RAG 的同学应该都知道，这个方式最大的问题就在于数据的搜索出来的准确性：

• 如果原始的问题在你的数据集里面本来就没有答案，凉凉
• 如果原始的问题在你的数据集里面有答案，但是你通过搜索的方式没找到，也凉了

我的总结和思考是：如果你本来就能通过搜索内容找到答案，那么借助 RAG 能更好的帮助你将答案组织为可读的逻辑给到用户；相反如果本身你的搜索能力就不及格，那就别指望它了。

微调

通过技术微调已有的模型，从而建立专业领域的模型，来完成特定领域场景的任务。

其实就是在一个预训练好的大型语言模型（基模）上，使用你指定的数据集对模型的一部分或全部参数进行额外的训练。目的是让模型更擅长解决你的特定任务或适应你的特定领域语言风格。

微调给我的感受有两个：

• 训练数据很重要，验证数据更重要。我往往找到了一大堆数据可以进行训练，但是如果仅仅只是训练，你是无法评估你微调前后的差别的。也就是说你无法评判一个微调模型的好坏，那你实际去用的时候其实是没底的。
• 没办法保证后续的训练不会对前面的训练有影响。

而微调其实现在已经比你想得要容易了，已经有了很多开源的解决方案来帮助你微调模型，你几乎只需要改改参数，就可以了，有的微调甚至还有 UI 可以直接选择等等。甚至一些云厂商可以直接支持数据微调，并直接提供微调后的模型运行。

最重要的是什么？成本！训练成本(小)+运行成本(大)，是否能支撑合理的运行成本是你是否要采用微调的关键。

MCP/Agent

通过外部服务能力，利用 AI 作为大脑，自动化原本的费时场景。MCP/Agent 可以作为手，直接触及到用户使用的场景和行为，帮助你完成一些“力所能及的事”。

这其实是一个很不错的结合场景，因为大多数 AI 仅仅只是对话的话能提供的帮助太少，或者说自动化程度不高。用户都是懒的，被 AI 会越惯越懒，他们（我）甚至只想动动嘴皮子，就把事情做了。所以，如果 AI 仅仅告诉你怎么做，那么还不够，如果能把事情直接完成，那才是尽善尽美的服务。

整个过程可以被抽象为：

• 规划：分解复杂目标为可执行的子任务。
• 工具使用：根据需求调用外部工具或服务(MCP)。
• 记忆：存储和利用历史信息。
• 反思：评估执行结果，修正错误或调整计划。。

如果你用过各种 AI 的 IDE 你会发现他们的很多设计也是这几个要点。将你的请求先思考，拆分为一个个任务，然后通过本地的各种 tools 去编写修改代码，然后去验证一下写的对不对，不对再调整，如果整个上下文长了还会总结之前的工作交给下一个对话继续操作。

在这里，最重要的部分是协作。是 AI 与工具的协作。我的思考是：一定要清晰的告诉 AI 你的工具能什么，而对于 MCP 来说，提供的选择有时候越少越好。有时候如果你没有清楚的告诉 AI 你的工具的能力，很有可能会被误用，而 MCP 有的时候是因为你提供的工具或者选择太多，导致 AI 误用了很多没必要的工具去操作。

浅谈与思考

妄自菲薄

千万不要妄自菲薄，我经常听到的一句话是：“用户是不是不需要我们这个产品，因为用户自己把东西交给 AI 提问也能得到结果” 错，哪怕你仅仅只是优化了 Prompt 加上了交互，也会有用户付费。路径缩短 或者说节约用户行为时间，这样的体验就会产生依赖。

数据为王

RAG 依赖高质量的知识库，微调需要大量标注精良的数据。然而，现实世界中，企业的文档散乱陈旧，用户数据涉及隐私难以获取，标注成本高昂且质量参差不齐。数据工程的质量和规模，往往直接决定了 AI 应用的成败上限，而这恰恰是很多项目（尤其是个人或小团队项目）最难逾越的鸿沟。 没有好数据，再好的模型也是“巧妇难为无米之炊”。

我的思考是这样一个例子，我自认为人类的大脑比 AI 强大（在私有领域），换作是我，收到 RAG 最终给我的 Prompt 我都无法解决这个问题，那我凭什么期待 AI 能解决呢？对于这个领域(私有)可能它知道并不比我多啊。

我都不知道公司打印机在哪里，AI 怎么会知道呢？

产品思维

掌握一项 AI 技术（如 RAG、微调）让我们具备了“能做”的能力，这很重要，是基础。但决定一个 AI 应用能否成功、能否真正产生价值的，是我们能否精准地找到那个“值得做”的问题，并用产品思维、工程能力和对用户的理解，将技术转化为切实的解决方案。 这个过程，远比调通一个 API、跑通一个微调脚本要复杂和艰难得多。它要求我们从技术的狂热中冷静下来，更深入地走进用户的真实世界，更务实地看待技术的边界与成本，更精心地设计产品与体验。

技术是锤子，但用户需要解决的问题才是那颗钉子。顺序反了，再好的锤子也敲不准。

MVP

最后是 最小可行产品 (MVP) + 快速迭代：，不要追求一上来就做一个完美的、功能繁多的应用。聚焦一个最核心用最快的速度（可能利用现成的 API、简单 RAG 或零样本/少样本提示工程）做出一个粗糙但能用的 MVP。尽快让真实用户用起来，收集反馈，验证价值假设。 基于反馈决定是放弃、转向还是深入优化（这时才可能需要微调、复杂 RAG 等）。

总结

技术会发展，新的与 AI 结合的技术还会不断出现，而结合 AI 开发应用，这场盛宴才刚刚开始，而找到那把开启真正价值之门的钥匙，需要我们所有人持续地思考、实践和反思。

🤗 Transformers 提供了便于快速下载和使用的 API，让你可以把预训练模型用在给定文本、在你的数据集上微调然后通过 model hub 与社区共享。同时，每个定义的 Python 模块都是完全独立的，便于修改和快速进行研究实验。

https://github.com/huggingface/transformers

简单说就是利用这个库可以快速简单帮我们微调模型，很多东西都封装好了可以直接拿来用。

准备

• 租一个服务器，我尝试的是 4090
• 选择一个支持 transformers 容器镜像环境
• 如果没有，也可以选择自己安装 https://github.com/huggingface/transformers/blob/main/i18n/README_zh-hans.md#%E5%AE%89%E8%A3%85

步骤

下载基模，使用 hf-mirror 会快，或者镜像环境如果支持魔法可以直接魔法下

1
2
3
4

$ cd /tmp
$ git lfs install
$ git clone https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct
$ cd Qwen2.5-7B-Instruct

微调代码

数据集处理 data_preprocess.py

这个部分需要根据你实际的具体数据格式进行处理，其中的关键就是读取已有的数据格式，将已有的数据格式转换为训练所需的数据集格式而已。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

import json
from torch.utils.data import Dataset

# 定义一个名为 MyDataset 的新类，它继承自 Dataset 类
class MyDataset(Dataset):
    # 定义类的初始化方法
    def __init__(self, data, tokenizer, args):
        super(MyDataset, self).__init__()
        self.data = data
        self.tokenizer = tokenizer
        self.prompt_column = args.prompt_column
        self.response_column = args.response_column
        self.max_source_length = args.max_source_length
        self.max_target_length = args.max_target_length

    # 返回数据集的长度
    def __len__(self):
        return len(self.data)

    # 通过索引访问数据集中的样本
    def __getitem__(self, i):
        item = self.data[i]

        # 获取消息列表
        messages = item["messages"]

        # 分离系统消息、用户消息和助手消息
        system_message = messages[0]  # 系统消息
        user_message = messages[1]    # 用户消息
        assistant_message = messages[2]  # 助手消息

        # 构建提示文本（系统消息 + 用户消息）
        prompt = build_prompt(system_message, user_message)

        # 构建响应文本（助手消息）
        response = build_response(assistant_message)

        # 对提示文本进行编码
        context = self.tokenizer(
            prompt,
            max_length=self.max_source_length,
            add_special_tokens=False)

        # 对响应文本进行编码
        response_encoding = self.tokenizer(
            response,
            max_length=self.max_target_length,
            add_special_tokens=False)

        # 将上下文和响应的 input_ids 连接起来
        input_ids = context["input_ids"] + response_encoding["input_ids"]

        # 将上下文和响应的注意力掩码连接起来
        attention_mask = context["attention_mask"] + response_encoding["attention_mask"]

        # 创建标签数组，标记上下文部分为 -100，响应部分使用真实的 input_ids
        labels = [-100] * len(context["input_ids"]) + response_encoding["input_ids"]

        # 确保输入 ID 和标签的长度一致
        assert len(input_ids) == len(labels), f"length mismatch: {len(input_ids)} vs {len(labels)}"

        # 返回编码后的数据
        return {
            "input_ids": input_ids,
            "attention_mask": attention_mask,
            "labels": labels
        }

# 构建提示文本
def build_prompt(system_message, user_message):
    # 获取系统消息内容和工具定义
    system_content = system_message["content"]
    tools = system_message.get("tools", [])

    # 获取用户消息内容
    user_content = user_message["content"]

    # 构建提示文本
    prompt = f"<|im_start|>system\n{system_content}"

    # 添加工具定义（如果有）
    if tools:
        tool_str = json.dumps(tools, ensure_ascii=False)
        prompt += f"\n\nTools: {tool_str}"

    # 添加用户消息
    prompt += f"\n<|im_end|>\n<|im_start|>user\n{user_content}\n<|im_end|>\n<|im_start|>assistant\n"

    return prompt

# 构建响应文本
def build_response(assistant_message):
    # 获取助手消息内容
    assistant_content = assistant_message["content"]

    # 构建响应文本
    response = f"{assistant_content}\n<|im_end|>"

    return response

看代码容易迷糊，直接看数据案例，首先是提示文本大概的样子，我们需要将原始的数据集转换为对话模型训练的格式，所以原始格式不重要，只要你最终能整成这样都可以。

1
2
3
4
5
6
7
8
9

<|im_start|>system
You are a helpful assistant.
<|im_end|>
<|im_start|>user
What is the capital of France?
<|im_end|>
<|im_start|>assistant
The capital of France is Paris.
<|im_end|>

然后是最终 tokenizer 后的样子

1
2
3
4
5

{
  'input_ids': tensor([ 101, 7429, 2105, 2019, 17341,  999, 2005, 3185, 4201, 14926, 2000, 7976, 22124,  102......]),
  'attention_mask': tensor([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, ....]),
  'labels': tensor(1)
}

微调 finetune.py

可以参考

• https://github.com/sahil280114/codealpaca/blob/2f78ddc5c682ed6738ad092bbbfa59ba915afcb0/train.py#L183
• https://github.com/ophiraShen/I-AM/blob/1f3bccc7e84c385f6f2bceb564d0b730c5627f89/models/glm_4_9b_chat/evaluate.py

网上还有很多，就不一一举例，直接让 GPT 写一个就好了，因为 transformers 都封装好了，其中最关键的还是在参数的设置上

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# 导入所需模块和库
import json
import torch
from transformers import (
    AutoTokenizer,
    AutoModelForCausalLM,
    BitsAndBytesConfig,
    DataCollatorForSeq2Seq,
    HfArgumentParser,
    TrainingArguments,
    Trainer
)
from peft import LoraConfig, TaskType, get_peft_model
from arguments import ModelArguments, DataTrainingArguments, PeftArguments
from data_preprocess import MyDataset

def main():
    # 解析命令行参数
    parser = HfArgumentParser((ModelArguments, DataTrainingArguments, PeftArguments, TrainingArguments))
    model_args, data_args, peft_args, training_args = parser.parse_args_into_dataclasses()

    # 加载预训练模型和分词器
    model = AutoModelForCausalLM.from_pretrained(model_args.model_name_or_path, torch_dtype=torch.bfloat16)
    tokenizer = AutoTokenizer.from_pretrained(model_args.model_name_or_path)

    # 设置LoRA配置
    lora_config = LoraConfig(
        inference_mode=False,
        task_type=TaskType.CAUSAL_LM,
        target_modules=["q_proj", "k_proj", "v_proj"],
        r=peft_args.lora_rank,
        lora_alpha=peft_args.lora_alpha,
        lora_dropout=peft_args.lora_dropout
    )
    # 应用LoRA配置到模型
    model = get_peft_model(model, lora_config).to("cuda")
    # 输出可训练参数数量
    model.print_trainable_parameters()

    # 设置数据规整器
    data_collator = DataCollatorForSeq2Seq(
        tokenizer=tokenizer,
        padding=True
    )

    # 读取训练数据
    if training_args.do_train:
        with open(data_args.train_file, "r", encoding="utf-8") as f:
            train_data = [json.loads(line) for line in f]
        # Dataset 处理数据
        train_dataset = Dataset(train_data, tokenizer, data_args)

    # 实例化Trainer
    trainer = Trainer(
        model=model,
        tokenizer=tokenizer,
        data_collator=data_collator,
        args=training_args,
        train_dataset=train_dataset if training_args.do_train else None,
        eval_dataset=eval_dataset if training_args.do_eval else None,
    )

    # 训练模型
    if training_args.do_train:
        model.gradient_checkpointing_enable()
        model.enable_input_require_grads()
        trainer.train()

if __name__ == "__main__":
    main()

启动脚本 train.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

#! /usr/bin/env bash

set -ex

LR=2e-4

DATESTR=`date +%Y%m%d-%H%M%S`
RUN_NAME=ft_linkinstar_qwen2
OUTPUT_DIR=output/${RUN_NAME}-${DATESTR}
mkdir -p $OUTPUT_DIR

# 修改你的模型路径
MODEL_PATH="/tmp/Qwen2.5-7B-Instruct"

CUDA_VISIBLE_DEVICES=0 python finetune.py \
    --do_train \
    --train_file ../data/train.jsonl \
    --model_name_or_path "${MODEL_PATH}" \
    --output_dir $OUTPUT_DIR \
    --max_source_length 2048 \
    --max_target_length 1024 \
    --per_device_train_batch_size 1 \
    --per_device_eval_batch_size 1 \
    --gradient_accumulation_steps 4 \
    --evaluation_strategy steps \
    --eval_steps 300 \
    --num_train_epochs 3 \
    --logging_steps 30 \
    --logging_dir $OUTPUT_DIR/logs \
    --save_steps 200 \
    --learning_rate $LR \
    --lora_rank 8 \
    --lora_alpha 32 \
    --lora_dropout 0.1 2>&1 | tee ${OUTPUT_DIR}/train.log

• 其中如果你租的 GPU 多可以调整 per_device_train_batch_size 和 per_device_eval_batch_size 更大 2、4…
• 然后其中 LR 是学习率
• response_column 和 prompt_column 是用来指定字段用的，不用看，因为没用到，我们直接处理数据内容为对应格式就好
• gradient_accumulation_steps 如果 GPU 内存够 48+ 可以减少

使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import argparse
from peft import PeftModel
from transformers import AutoTokenizer, AutoModelForCausalLM

def load_model(model_path, checkpoint_path):
    tokenizer = AutoTokenizer.from_pretrained(model_path)
    model = AutoModelForCausalLM.from_pretrained(model_path, torch_dtype=torch.bfloat16)
    model = PeftModel.from_pretrained(model, model_id=checkpoint_path).to("cuda").eval()
    return tokenizer, model

# 初始化全局变量
parser = argparse.ArgumentParser()
parser.add_argument("--model", type=str, default=None, required=True, help="main model weights")
parser.add_argument("--ckpt", type=str, default=None, required=True, help="The checkpoint path")
args = parser.parse_args()

# 加载模型
tokenizer, model = load_model(args.model, args.ckpt)

parser = argparse.ArgumentParser()
parser.add_argument("--model", type=str, default=None, required=True, help="main model weights")
parser.add_argument("--ckpt", type=str, default=None, required=True, help="The checkpoint path")
args = parser.parse_args()

tokenizer, model = load_model(args.model, args.ckpt)

# 获取模型生成的回复
def get_completion(prompt):
    inputs = tokenizer([prompt], return_tensors="pt").to("cuda")
    with torch.no_grad():
        outputs = model.generate(**inputs, max_new_tokens=1024)
        response = tokenizer.decode(outputs[:,inputs['input_ids'].shape[1]:][0], skip_special_tokens=True)
    return response

总结

经过这段时间的尝试和实践，总结如下几点：

• 定向场景小模型够用
• 模型训练成本低，测试成本高
• 数据集非常重要
• transformers 微调已经非常易用了

本文将带你使用 ollama + mcp-go + cherry-studio 在本地实现并构建完整的一套流程。

在 MCP 的风吹了那么久之后，相信你已经看过不少介绍了，如果你还没有实际体验过 MCP 的魅力，又或者你想通过 Golang 构建一个 MCP 服务，那么就来看看吧。

准备

• 框架 https://github.com/mark3labs/mcp-go/
• 对话客户端 https://github.com/CherryHQ/cherry-studio 所有支持 MCP 的客户端都可以再比如 Claude Desktop
• 模型使用 ollama 跑一个 qwen2.5:7b 当然如果你本地无法运行也可以接入线上各个厂商提供的模型

解释

首先快速白话解释一下什么是 MCP ？

在没有 MCP 的时候

• 用户：大模型，帮我点个外卖
• 大模型：好的，我将告诉你，点外卖的步骤是….但你得自己点，因为我没有“手”

当有了 MCP 之后

• 用户：大模型，帮我点个外卖
• 大模型：好的，鳄了 MCP 服务去帮我下单一杯咖啡
• 鳄了 MCP 服务：收到，咖啡订单已提交

所以，其实你不用了解太多的细节，也能知道 MCP 是做什么用的。关键就是，大模型本身仅提供了对话的能力，而想要实际操作一些东西的时候，它无法触及，而此时外部系统通常的做法是提供一些 API 接口，让其他系统能够调用自己，从而提供服务。而 API 的问题在于每家都有自己的参数列表和返回结果，MCP 的优势是在于制定了协议统一了接入的规范，从而让各个系统都能轻松的被大模型调用。从宏观的角度看，就是给大模型装上了 “手” 让他能触及实际的业务场景。

目标

我网上看了很多有关 MCP 实现案例的文章，发现一个共同的问题，大部分都在提供了一个工具服务为加法，a+b = c 这样。但是这完全体现不出 MCP 的意义（我的大模型自己不会算吗？非得你 MCP 教我？[狗头]）。所以我们这次的目标是让大模型可以直接操作你本地的文件系统，从而体会到 MCP 的魅力。

直接上代码

不搞哪些花里胡哨的东西，直接上代码，而且非常简单，一看就懂。

tools.go

首先定义两个方法，用于操作本地的目录文件

• listFiles 用于查询目录下的所有文件
• renameFile 由于重命名一个文件
  directoryPath 设置了仅允许操作的文件目录，防止大模型看到一些不该看的小视频

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

package main

import (
"errors"
"fmt"
"os"
"path/filepath"
"strings"
)

const (
directoryPath = "/tmp/linkinstar"
)

func listFiles(directory string, extension string) ([]string, error) {
if strings.TrimSpace(directory) != directoryPath {
return nil, errors.New(fmt.Sprintf("我无法访问目录 %s", directory))
}

fmt.Println("Listing files in directory :", directory)

files, err := os.ReadDir(directory)
if err != nil {
return nil, err
}

var result []string
for _, file := range files {
if file.IsDir() {
continue
}
if extension == "" || strings.HasSuffix(file.Name(), extension) {
result = append(result, file.Name())
}
}

return result, nil
}

func renameFile(directory string, oldName string, newName string) ([]string, error) {
if strings.TrimSpace(directory) != directoryPath {
return nil, errors.New(fmt.Sprintf("我无法访问目录 %s", directory))
}

fmt.Println("Renaming file:", oldName, "to", newName)

err := os.Rename(filepath.Join(directory, oldName), filepath.Join(directory, newName))
if err != nil {
return nil, err
}
return listFiles(directory, "")
}

main.go

将两个 tools 注册并添加到服务中，最后启动了一个 SSE 的服务。注册时可以看到我们指定了输入的必要参数。具体这里就不过多解释 SSE 是什么了，当然 MCP 也提供了其他接入的方式，比如标准的输入输出等等，这里以 SSE 举例。AddTool 内的实现方法也非常简单，就是获取参数，调用前一步的 方法 ，然后处理并返回结果即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

package main

import (
"context"

"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
)

func main() {
s := server.NewMCPServer("File manager server", "1.0.0")

// 添加工具，查询 /tmp 下的目录
listFilesTool := mcp.NewTool("list_files", mcp.WithDescription("列出指定目录下的文件"),
mcp.WithString("directory", mcp.Required(), mcp.Description("要列出文件的目录")),
mcp.WithString("extension", mcp.Description("要过滤的文件扩展名")),
)
s.AddTool(listFilesTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
directory := request.Params.Arguments["directory"].(string)
extension := request.Params.Arguments["extension"].(string)

files, err := listFiles(directory, extension)
if err != nil {
return mcp.NewToolResultText(err.Error()), nil
}

res := "文件列表:\n"
for _, file := range files {
res += file + "\n"
}

return mcp.NewToolResultText(res), nil
})

// 添加工具，重命名文件
renameFileTool := mcp.NewTool("rename_file", mcp.WithDescription("重命名文件"),
mcp.WithString("directory", mcp.Required(), mcp.Description("要重命名文件的目录")),
mcp.WithString("old_name", mcp.Required(), mcp.Description("要重命名的旧文件名")),
mcp.WithString("new_name", mcp.Required(), mcp.Description("新的文件名")),
)
s.AddTool(renameFileTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
directory := request.Params.Arguments["directory"].(string)
oldName := request.Params.Arguments["old_name"].(string)
newName := request.Params.Arguments["new_name"].(string)

files, err := renameFile(directory, oldName, newName)
if err != nil {
return nil, err
}

res := "重命名后的文件列表:\n"
for _, file := range files {
res += file + "\n"
}

return mcp.NewToolResultText(res), nil
})

err := server.NewSSEServer(s).Start(":9999")
if err != nil {
panic(err)
}
return
}

测试

测试前请保证大模型本身支持 MCP 并正常运行，我使用的是：ollama run qwen2.5:7b

配置 MCP 服务

配置非常简单，只需要配置一个 http://127.0.0.1:9999/sse 地址就可以了

记得需要在对话前启用指定的 MCP 服务哦

对话测试

如果你可以看到在对话中客户端主动调用了你的 MCP 服务证明成功了

可以看到，大模型可以理解我们的要求，并调用对应所需要的 MCP 服务从而实现对应的操作。现在大模型的手已经可以伸到我们本地来咯。

扩展与总结

扩展

除了我们上面案例中提到通过 AddTool 方法告诉大模型你提供了哪一些工具，另外还有 AddResource AddPrompt 提供可访问的资源以及最佳实践的一些提示词等。

在上面的案例中我们只是简单的列表和重命名了本地的文件，你可以进一步扩展，比如制作一个本地的文件自动管理工具，自动将杂乱无序的文件以一种合理的顺序归类并整理好。

总结

就像前面提到的那样，MCP 就像是给大模型装上了 “手” ，大脑（大模型）负责处理我们说的指令，将指令拆分成各个动作，然后调用各个协调系统（MCP）最终完成这个指令的工作。相信你看完本文应该不仅能快速上手 MCP 的使用，还能体会到 MCP 的魅力所在。那么赶紧试试吧，去构建你自己的 MCP 服务吧。

📢 注意，该文本非最终版本，正在更新中，版权所有，请勿转载！！

前言

在 k8s 中 pod 之间的访问在所难免，多个系统之间往往有着调用和互动。那么他们之间的访问就离不开 DNS 的帮助，两个相同 namespace 下的 pod 可以直接通过名称访问，而不同 namespace 下也只需要加上 namespace 就可以了。而实现的关键就是我们的 “交通指挥员” Core-DNS。

前置知识

• Core-DNS 的基本功能
• 简单的了解 caddy

心路历程

第一次知道它是哪个时候还是 kube-dns，后来才是 Core-DNS。因为在整个系统安装好之后，就会有一个 pod 名字带 core-dns 的 pod。我当时就好奇这个 pod 是干什么的，于是就去研究，后来才知道它是负责 DNS 的。今天我们就来一起读读 Core-DNS 的源码，看看它是如何工作的。

码前提问

在看实际的源码之前，首先我们要明白 Core-DNS 的基本架构和工作原理。Core-DNS 本质是一个灵活的 DNS 服务器，我们知道 DNS 服务器的主要功能是解析域名，将域名转换为 IP 地址。而 Core-DNS 解析的域名不是普通的域名，而是 Kubernetes 集群中的服务和 Pod 的域名。而 IP 地址则是 Pod 的 IP 地址。从而让 pod 之间访问的时候不要用记不住的 IP 地址，而且 IP 地址还会变动。那么其实我们最关心的就是 Core-DNS 是如何知道 Pod 的 IP 地址的，以及它是如何处理 DNS 查询的。

1. Core-DNS 是如何知道 pod 的 IP 地址的？
2. Core-DNS 是如何处理 DNS 查询的？
3. Core-DNS 有什么优化措施来提高性能？

源码分析

首先 Core-DNS 在 https://github.com/coredns/coredns

由于 Core-DNS 其实是利用了老版本的 caddy 作为一个启动器，而所有必要的功能都是以插件的形式存在的，所以看源码的时候可能会跳出这个仓库本身。并且跳出去之后可能通过查看引用的方式是没有办法直接跳回来的，所以请注意跳转的时候记住来源。

入口

入口其实特别简单，就在最外面的文件中，引入插件，然后调用 coremain.Run() 启动 Core-DNS。

1
2
3
4
5
6
7
8
9

// coredns.go
import (
    _ "github.com/coredns/coredns/core/plugin" // Plug in CoreDNS.
    "github.com/coredns/coredns/coremain"
)

func main() {
    coremain.Run()
}

然后你点进去 coremain.Run() 就会发现懵了，因为其本质是在启动一个 caddy 实例。而并没有任何调用 Core-DNS 的代码。怎么回事呢？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// Run is CoreDNS's main() function.
func Run() {
    caddy.TrapSignals()
    flag.Parse()

    if len(flag.Args()) > 0 {
        mustLogFatal(fmt.Errorf("extra command line arguments: %s", flag.Args()))
    }

    log.SetOutput(os.Stdout)
    log.SetFlags(LogFlags)

    if version {
        showVersion()
        os.Exit(0)
    }
    if plugins {
        fmt.Println(caddy.DescribePlugins())
        os.Exit(0)
    }

    _, err := maxprocs.Set(maxprocs.Logger(log.Printf))
    if err != nil {
        log.Println("[WARNING] Failed to set GOMAXPROCS:", err)
    }

    // Get Corefile input
    corefile, err := caddy.LoadCaddyfile(serverType)
    if err != nil {
        mustLogFatal(err)
    }

    // Start your engines
    instance, err := caddy.Start(corefile)
    if err != nil {
        mustLogFatal(err)
    }

    if !dnsserver.Quiet {
        showVersion()
    }

    // Twiddle your thumbs
    instance.Wait()
}

此时，不要慌，我们可以尝试去 caddy.Start 里面看看，就会看到其实调用关系是 caddy.Start -> startWithListenerFds -> inst.context.MakeServers 。而其中的 context 是一个接口

1
2
3
4
5
6
7
8
9

type Context interface {
    InspectServerBlocks(string, []caddyfile.ServerBlock) ([]caddyfile.ServerBlock, error)

    // This is what Caddy calls to make server instances.
    // By this time, all directives have been executed and,
    // presumably, the context has enough state to produce
    // server instances for Caddy to start.
    MakeServers() ([]Server, error)
}

而在我们的 /core/dnsserver/register.go 有一个 dnsContext 实现了这个接口。

1
2
3
4
5
6
7

// core/dnsserver/register.go:37
type dnsContext struct {
    keysToConfigs map[string]*Config

    // configs is the master list of all site configs.
    configs []*Config
}

而且其中的 MakeServers 方法就是我们需要的。它会调用 makeServersForGroup 方法来创建服务器实例。如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// core/dnsserver/register.go:301
func makeServersForGroup(addr string, group []*Config) ([]caddy.Server, error) {
    //....

    var servers []caddy.Server
    for range numSockets {
        // switch on addr
        switch tr, _ := parse.Transport(addr); tr {
        case transport.DNS:
            s, err := NewServer(addr, group)
            // ...
        case transport.TLS:
            s, err := NewServerTLS(addr, group)
            // ...
        case transport.QUIC:
            s, err := NewServerQUIC(addr, group)
            // ...
        case transport.GRPC:
            s, err := NewServergRPC(addr, group)
            // ...
        case transport.HTTPS:
            s, err := NewServerHTTPS(addr, group)
            // ...
        }
    }
    return servers, nil
}

看到这里的 NewServer 方法了吗？它就是我们 Core-DNS 的核心服务器。我们可以继续深入看看它的实现。而 NewServer 创建的 Server 是实现了 caddy.TCPServer 和 caddy.UDPServer 接口的，即是有 Serve 和 ServePacket 方法的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// core/dnsserver/server.go:148
func (s *Server) Serve(l net.Listener) error {
    s.m.Lock()

    s.server[tcp] = &dns.Server{Listener: l,
        Net:           "tcp",
        TsigSecret:    s.tsigSecret,
        MaxTCPQueries: tcpMaxQueries,
        ReadTimeout:   s.readTimeout,
        WriteTimeout:  s.writeTimeout,
        IdleTimeout: func() time.Duration {
            return s.idleTimeout
        },
        Handler: dns.HandlerFunc(func(w dns.ResponseWriter, r *dns.Msg) {
            ctx := context.WithValue(context.Background(), Key{}, s)
            ctx = context.WithValue(ctx, LoopKey{}, 0)
            s.ServeDNS(ctx, w, r)
        })}

    s.m.Unlock()

    return s.server[tcp].ActivateAndServe()
}

到这里，其实对于整个启动过程我们有了一个大致的认识，这里非常绕的原因是因为它的启动依赖于 Caddy ，所以真正的运行是在那边里面，而这里仅仅只是实现了必要的接口而已。所以有时候看源码单独只是看本仓库，往往会完全不理解在干什么，这件事告诉我们，有的时候如果看不明或找不到一些入口的时候，可能是因为它依赖了其他仓库的代码。

插件系统核心

其实插件本身并不复杂，在这里插件的实现就仅仅是实现接口，然后注册，最后被调用而已。接口是下面这样：

1
2
3
4
5

// plugin/plugin.go:50
Handler interface {
    ServeDNS(context.Context, dns.ResponseWriter, *dns.Msg) (int, error)
    Name() string
}

而注册就更简单了

1

func init() { plugin.Register("whoami", setup) }

就是在每个插件的 init 函数中调用 plugin.Register 方法来注册插件。这样在 Core-DNS 启动时就会自动加载这些插件。当然，不要忘记本分，我们今天最重要的目的是看它在 k8s 中是如何配合工作的，所以我们需要关注的是 Kubernetes 插件的实现。

Kubernetes 插件分析

相比与其他插件，kubernetes 插件代码就要多的多了。Kubernetes 插件是 Core-DNS 的核心，负责与 K8s API 交互。首先让我们来看到注册的部分：

1
2
3
4

// plugin/kubernetes/setup.go:26
const pluginName = "kubernetes"

func init() { plugin.Register(pluginName, setup) }

和其他插件一样，没什么好说的，继续，我们来看看 setup 函数，其中调用了 InitKubeCache 这个方法里面调用了 newdnsController 这是我们的关键：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

// plugin/kubernetes/controller.go:130
func newdnsController(ctx context.Context, kubeClient kubernetes.Interface, mcsClient mcsClientset.MulticlusterV1alpha1Interface, opts dnsControlOpts) *dnsControl {
    dns := dnsControl{
        client:            kubeClient,
        mcsClient:         mcsClient,
        selector:          opts.selector,
        namespaceSelector: opts.namespaceSelector,
        stopCh:            make(chan struct{}),
        zones:             opts.zones,
        endpointNameMode:  opts.endpointNameMode,
        multiclusterZones: opts.multiclusterZones,
    }

    dns.svcLister, dns.svcController = object.NewIndexerInformer(
        &cache.ListWatch{
            ListFunc:  serviceListFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
            WatchFunc: serviceWatchFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
        },
        &api.Service{},
        cache.ResourceEventHandlerFuncs{AddFunc: dns.Add, UpdateFunc: dns.Update, DeleteFunc: dns.Delete},
        cache.Indexers{svcNameNamespaceIndex: svcNameNamespaceIndexFunc, svcIPIndex: svcIPIndexFunc, svcExtIPIndex: svcExtIPIndexFunc},
        object.DefaultProcessor(object.ToService, nil),
    )

    podLister, podController := object.NewIndexerInformer(
        &cache.ListWatch{
            ListFunc:  podListFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
            WatchFunc: podWatchFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
        },
        &api.Pod{},
        cache.ResourceEventHandlerFuncs{AddFunc: dns.Add, UpdateFunc: dns.Update, DeleteFunc: dns.Delete},
        cache.Indexers{podIPIndex: podIPIndexFunc},
        object.DefaultProcessor(object.ToPod, nil),
    )
    dns.podLister = podLister
    if opts.initPodCache {
        dns.podController = podController
    }

    epLister, epController := object.NewIndexerInformer(
        &cache.ListWatch{
            ListFunc:  endpointSliceListFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
            WatchFunc: endpointSliceWatchFunc(ctx, dns.client, api.NamespaceAll, dns.selector),
        },
        &discovery.EndpointSlice{},
        cache.ResourceEventHandlerFuncs{AddFunc: dns.Add, UpdateFunc: dns.Update, DeleteFunc: dns.Delete},
        cache.Indexers{epNameNamespaceIndex: epNameNamespaceIndexFunc, epIPIndex: epIPIndexFunc},
        object.DefaultProcessor(object.EndpointSliceToEndpoints, dns.EndpointSliceLatencyRecorder()),
    )
    dns.epLister = epLister
    if opts.initEndpointsCache {
        dns.epController = epController
    }

    dns.nsLister, dns.nsController = object.NewIndexerInformer(
        &cache.ListWatch{
            ListFunc:  namespaceListFunc(ctx, dns.client, dns.namespaceSelector),
            WatchFunc: namespaceWatchFunc(ctx, dns.client, dns.namespaceSelector),
        },
        &api.Namespace{},
        cache.ResourceEventHandlerFuncs{},
        cache.Indexers{},
        object.DefaultProcessor(object.ToNamespace, nil),
    )

    //....

    return &dns
}

看到熟悉的 Informer 了吗？它是 Kubernetes 的核心组件之一，用于监听和缓存 Kubernetes API 对象的变化。这里我们创建了多个 Informer，分别用于监听 Service、Pod、Endpoints 和 Namespace 的变化。我们知道，不管是在同一个 namespace 还是不同 namespace 下，Pod 都可以通过 DNS 名称访问其他 Pod。所以这些不同的事件变动都要监听。而这几个资源的变化都会触发 注册的 eventHandler 也就是 Add、Update 和 Delete 方法。

你一定以为 Add、Update 和 Delete 这些方法会具体处理数据？但其实你实际去看看，他们其实本质都是去更新了一下时间戳而已。而真正的数据 cache 在 cache.Indexers 里面，在 dnsControl 中有几个 cache.Indexer 专门用了放他们。而本地缓存的意义就在于避免去频繁的访问 Kubernetes API Server，这是显而易见的。

其中有一个 podLister cache.Indexer 我们后面还会看到。

ServeDNS

最后我们来看看请求来的时候是如何处理的，而这里的关键则就在与 ServeDNS 方法了

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// plugin/kubernetes/handler.go:13
func (k Kubernetes) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
    //....
    switch state.QType() {
    case dns.TypeA:
        records, truncated, err = plugin.A(ctx, &k, zone, state, nil, plugin.Options{})
    case dns.TypeAAAA:
        records, truncated, err = plugin.AAAA(ctx, &k, zone, state, nil, plugin.Options{})
    case dns.TypeTXT:
        records, truncated, err = plugin.TXT(ctx, &k, zone, state, nil, plugin.Options{})
    case dns.TypeCNAME:
        records, err = plugin.CNAME(ctx, &k, zone, state, plugin.Options{})
    case dns.TypePTR:
        records, err = plugin.PTR(ctx, &k, zone, state, plugin.Options{})
    case dns.TypeMX:
        records, extra, err = plugin.MX(ctx, &k, zone, state, plugin.Options{})
    case dns.TypeSRV:
        records, extra, err = plugin.SRV(ctx, &k, zone, state, plugin.Options{})
    case dns.TypeSOA:
        if qname == zone {
            records, err = plugin.SOA(ctx, &k, zone, state, plugin.Options{})
        }
    case dns.TypeAXFR, dns.TypeIXFR:
        return dns.RcodeRefused, nil

    //....
    return dns.RcodeSuccess, nil
}

可以看到，这里会根据不同的 DNS 查询类型来调用不同的处理方法。比如对于 A 记录查询，会调用 plugin.A 方法，而对于 AAAA 记录查询，则会调用 plugin.AAAA 方法。这些方法会根据当前的状态和查询条件来返回相应的 DNS 记录。

而最终不同的方法都会转回到 Services 方法中，通过 k.Records(ctx, state, false) 最后我们可以确认我们找到了，findPods 方法

1
2
3
4
5
6
7

// plugin/kubernetes/kubernetes.go:95
func (k *Kubernetes) Services(ctx context.Context, state request.Request, exact bool, opt plugin.Options) (svcs []msg.Service, err error) {
    //...
    s, e := k.Records(ctx, state, false)
    //...
    return internal, e
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// plugin/kubernetes/kubernetes.go:310
func (k *Kubernetes) Records(ctx context.Context, state request.Request, exact bool) ([]msg.Service, error) {
    //...
    if r.podOrSvc == Pod {
        pods, err := k.findPods(r, state.Zone)
        return pods, err
    }

    var services []msg.Service
    var err error
    if !multicluster {
        services, err = k.findServices(r, state.Zone)
    } else {
        services, err = k.findMultiClusterServices(r, state.Zone)
    }
    return services, err
}

而 findPods 当我看到这个名字的时候我就知道距离胜利不远了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// plugin/kubernetes/kubernetes.go:359
func (k *Kubernetes) findPods(r recordRequest, zone string) (pods []msg.Service, err error) {
    //...

    zonePath := msg.Path(zone, coredns)

    var ip string
    if strings.Count(podname, "-") == 3 && !strings.Contains(podname, "--") {
        ip = strings.ReplaceAll(podname, "-", ".")
    } else {
        ip = strings.ReplaceAll(podname, "-", ":")
    }

    //...

    for _, p := range k.APIConn.PodIndex(ip) {
        // check for matching ip and namespace
        if ip == p.PodIP && match(namespace, p.Namespace) {
            s := msg.Service{Key: strings.Join([]string{zonePath, Pod, namespace, podname}, "/"), Host: ip, TTL: k.ttl}
            pods = append(pods, s)

            err = nil
        }
    }
    return pods, err
}

显然这里就是对于请求的 Pod 的 IP 地址进行查询。我们只需要去看 PodIndex 方法就可以了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// plugin/kubernetes/controller.go:504
func (dns *dnsControl) PodIndex(ip string) (pods []*object.Pod) {
    os, err := dns.podLister.ByIndex(podIPIndex, ip)
    if err != nil {
        return nil
    }
    for _, o := range os {
        p, ok := o.(*object.Pod)
        if !ok {
            continue
        }
        pods = append(pods, p)
    }
    return pods
}

而这个方法中的 podLister 就是我们之前看到的 podLister cache.Indexer 。它就是 Indexer 缓存。里面存放的就是 Pod 的信息。而 ByIndex 方法则是根据索引来查询 Pod 的信息。

至此整个链路就全部串起来了。

码后解答

1. Core-DNS 是如何知道 pod 的 IP 地址的？

• 还是老一套 Informer 机制而已，Core-DNS 通过 Kubernetes 的 API Server 获取 Pod 的信息，并将其缓存到本地的 cache.Indexer 中。每当 Pod 的信息发生变化时，相关的 Informer 会触发事件，更新缓存中的 Pod 信息。

2. Core-DNS 是如何处理 DNS 查询的？

• 其实本质就是启动一个 DNS 服务，只不过它对于 DNS 查询会处理 k8s 中的服务和 Pod 的域名解析而已。

3. Core-DNS 有什么优化措施来提高性能？

• cache 机制，Core-DNS 使用了本地缓存来存储 Pod 和 Service 的信息，避免频繁访问 Kubernetes API Server。通过 Informer 机制监听资源变化，并更新本地缓存，从而提高查询性能。

总结提升

插件机制

其实 Core DNS 本质里面有两种模式在里面，一个是对于 caddy 的套壳，它完全是利用了 caddy 作为了一个启动器，虽然从代码层面来说减少了很多项目启动运行部分的代码，但是实际中我们也看到了，它已经删除了 caddy 许多功能，完全与主干已经脱节了。所以其实它完全可以把那部分直接合并过来作为一个项目里面。我们在看代码的时候会发现跳来跳去，非常的麻烦。对于新人确实不好理解。而另一个模式是 plugin 机制，利用 golang 中的 init 方法实现注册，只要 import 了就会自动注册。很多插件系统的设计也都是如此。

Informer

最后提一次它吧，一路看到这里，我相信你已经明白为什么很多人吹 Informer 了。它的设计确实非常的巧妙，利用了缓存和事件驱动的方式来处理 Kubernetes 中的资源变化，而且无论是内部组件还是外部组件都可以用它。通过 Informer，我们可以轻松地监听和处理资源的增删改查，而不需要频繁地访问 API Server。这种设计大大提高了性能和效率。而最关键的是利用了它，所有其他想要扩展 Kubernetes 的功能都可以利用它一方面是简化了开发工作，一方面接入行为也统一。

📢 注意，该文本非最终版本，正在更新中，版权所有，请勿转载！！

前言

前面说完了 Service 和 kube-proxy，那就自然轮到了我们的 Ingress 了。Ingress 作为 Kubernetes 中负责外部流量路由的重要组件，其实现原理和设计思路值得我们深入研究。当然，这里也要说明的是，对于 Ingress 其实在这个版本里面已经有一点点 “落伍” ，官方更为推荐的是使用 Kubernetes Gateway API 来做同样的事情，并且能力更为强大。支持更丰富的协议，更精细化的流量控制，以及对于权限的控制等等。不过在这里不涉及这个部分，感兴趣同学可以自行去查看相关源码。

前置知识

• Ingress
• Ingress Controller

心路历程

之前我也写过对于 Ingress 的基础概念的说明，我称为 service 的 service。其实这个对象的出现是一种顺理成章的事情，对于一个多业务场景下的方案来说，不同域名访问不同服务，一定会需要一个网关这样的角色。而对于大的场景还是小的场景都需要不同的网关去做处理，但实际的能力大差不差。我们最熟悉的就是 https://github.com/kubernetes/ingress-nginx 。所以本文也将以它为源码分析的对象。

码前提问

同样的，在开始源码分析之前，让我们先思考几个问题：

1. ingress-nginx 本身究竟是个什么东西？
2. Ingress Controller 是如何监听到 Ingress 资源的变化的？
3. Ingress Controller 是如何将规则转换为实际的负载均衡配置的？

源码分析

Ingress 数据结构

先看一下我们熟悉的 yaml 配置

1
2
3
4
5
6
7
8
9
10
11

rules:
    - host: api.linkinstars.com
      http:
        paths:
          - path: /user
            pathType: Prefix
            backend:
              service:
                name: user
                port:
                  number: 8080

数据结构的部分，我相信你很容易可以找到对应的部分。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// staging/src/k8s.io/api/networking/v1beta1/types.go:35
type Ingress struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    Spec IngressSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
    Status IngressStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`
}

// staging/src/k8s.io/api/networking/v1beta1/types.go:73
type IngressSpec struct {
    IngressClassName *string `json:"ingressClassName,omitempty" protobuf:"bytes,4,opt,name=ingressClassName"`
    Backend *IngressBackend `json:"backend,omitempty" protobuf:"bytes,1,opt,name=backend"`
    TLS []IngressTLS `json:"tls,omitempty" protobuf:"bytes,2,rep,name=tls"`
    Rules []IngressRule `json:"rules,omitempty" protobuf:"bytes,3,rep,name=rules"`
}

所以 Ingress 对象本身很简单，就是记录路由的规则，而这个规则则是 Ingress Controller 最为关注的东西。下面我们就来看看我们今天的重点，也就是 ingress-nginx 的具体实现。注意下面的源码都来自于它，而不是 k8s 主项目中。

ingress-nginx

如果你对于 ingress-nginx 不是特别熟悉，强烈建议使用一次，一次就懂。然后可以先看：ingress-nginx/deploy/static/provider/cloud/deploy.yaml 部署。看了这个文件其实对于它本身你就觉得不是什么很可怕的东西了。其中抛开角色、权限、配置相关对象之外就只有：

• 一个名叫 ingress-nginx-controller 的 Service
• 一个名叫 ingress-nginx-controller 的 Deployment
• 一个名叫 nginx 的 IngressClass

其他可以忽略，重点其实就是他们几个。其实看到 Deployment 的时候，我就已经一下子明白了。其实本质它还是一个 Deployment 服务而已，而 Service 是一个 LoadBalancer 。相信到此你应该已经了解基本的结构了，在没有看源码的时候你就可以大胆去猜测了，可能它就是通过一个服务去获取路由规则，而通过 LB 把流量接进来，通过 nginx 的实例将流量按规则去路由而已。而得益于 nginx 本身的路由强大，性能通常也没有什么问题。

那么本文的两个关键问题就来了：

• ingress-nginx 如何知道规则变动了？
• ingress-nginx 如何把 ingress 的规则转换为 nginx 的规则？

Ingress Controller 实现原理

还是老套路，由于这是一个独立的服务，所以我们直接从入口着手：

入口到对象

入口特别好找，和大多数项目一样就在 cmd 下面，main 的函数开始。其中我对于入口函数精简了绝大多数代码，留下了与我们最相关的部分

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// cmd/nginx/main.go:53
func main() {
    kubeClient, err := createApiserverClient(conf.APIServerHost, conf.RootCAFile, conf.KubeConfigFile)

    _, err = kubeClient.NetworkingV1().IngressClasses().List(context.TODO(), metav1.ListOptions{})
    if err != nil {
        if !errors.IsNotFound(err) {
            if errors.IsForbidden(err) {
                klog.Warningf("No permissions to list and get Ingress Classes: %v, IngressClass feature will be disabled", err)
                conf.IngressClassConfiguration.IgnoreIngressClass = true
            }
        }
    }
    conf.Client = kubeClient

    err = k8s.GetIngressPod(kubeClient)
    if err != nil {
        klog.Fatalf("Unexpected error obtaining ingress-nginx pod: %v", err)
    }

    ngx := controller.NewNGINXController(conf, mc)

    go ngx.Start()

    process.HandleSigterm(ngx, conf.PostShutdownGracePeriod, func(code int) {
        os.Exit(code)
    })
}

其中我们可以看到：

1. 通过 createApiserverClient 创建了一个 kubeClient ，然后尝试调用 API 拉取了一下 Ingress 的信息，如果拉取不到则说明没有权限。
2. 然后获取了一下 IngressPod。
3. 最重要的就是通过 controller.NewNGINXController 创建我们的主角 controller 并通过 Start 启动起来。

啊哈，其实从这里的 ApiserverClient 你就已经大概能猜到如何拿到相关信息的了，当然，所有其实 k8s 相关的扩展能力组件都与这个 apiserver 有着关系，因为就是通过它来控制对象或者获取相关资源的信息。

最后 process.HandleSigterm 其实这部分也是可以抄的，我们放在最后说。

初始化

首先来看看 NewNGINXController 创建的时候究竟干了什么。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// internal/ingress/controller/nginx.go:76
func NewNGINXController(config *Configuration, mc metric.Collector) *NGINXController {
    // ....

    n := &NGINXController{
        // ....
    }

    // ....

    n.store = store.New(
        config.Namespace,
        config.WatchNamespaceSelector,
        config.ConfigMapName,
        config.TCPConfigMapName,
        config.UDPConfigMapName,
        config.DefaultSSLCertificate,
        config.ResyncPeriod,
        config.Client,
        n.updateCh,
        config.DisableCatchAll,
        config.DeepInspector,
        config.IngressClassConfiguration,
        config.DisableSyncEvents)

    n.syncQueue = task.NewTaskQueue(n.syncIngress) // 注意一下这里的这个，后面有用
    // ...

    return n
}

有关 nginx 的部分以及模板的部分都不是我们的重点，因为我们关心的还是 k8s 上，于是在仔细寻找后发现有一个 store 的对象让我找到了关键点。

你别说，这个 store.New 有足足 600+ 行的代码，都看是不可能都看的。

PS：注释特别加了 nolint:gocyclo，可见复杂的别人都懒的动了，不然对于这样长的函数还是拆分为多个可读性会更好

为什么这么长呢？原因其实是因为写了一大堆的闭包在里面，而其实最重要的放在了最后

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// internal/ingress/controller/store/store.go:850
if _, err := store.informers.Ingress.AddEventHandler(ingEventHandler); err != nil {
    klog.Errorf("Error adding ingress event handler: %v", err)
}
if !icConfig.IgnoreIngressClass {
    if _, err := store.informers.IngressClass.AddEventHandler(ingressClassEventHandler); err != nil {
        klog.Errorf("Error adding ingress class event handler: %v", err)
    }
}
if _, err := store.informers.EndpointSlice.AddEventHandler(epsEventHandler); err != nil {
    klog.Errorf("Error adding endpoint slice event handler: %v", err)
}
if _, err := store.informers.Secret.AddEventHandler(secrEventHandler); err != nil {
    klog.Errorf("Error adding secret event handler: %v", err)
}
if _, err := store.informers.ConfigMap.AddEventHandler(cmEventHandler); err != nil {
    klog.Errorf("Error adding configmap event handler: %v", err)
}
if _, err := store.informers.Service.AddEventHandler(serviceHandler); err != nil {
    klog.Errorf("Error adding service event handler: %v", err)
}

看到这里其实就很清楚了，关键是就实现了 informer 的各种 event handler，然后对于各种事件做了不同的处理。其中就有 ingress 的事件。而在对应的 ingEventHandler 处理方法中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ingEventHandler := cache.ResourceEventHandlerFuncs{
    AddFunc: func(obj interface{}) {
        ing, _ := toIngress(obj)

        //...

        store.syncIngress(ing)
        store.updateSecretIngressMap(ing)
        store.syncSecrets(ing)

        updateCh.In() <- Event{
            Type: CreateEvent,
            Obj:  obj,
        }
    },

关键就是将各种事件放到 updateCh 里面去。这里的这个 updateCh 又是我们可以学习的一个小点，它其实是一个 RingChannel 并且其实这库已经不更新了，但这里依旧沿用了，说明一个 10 年前设计的库还是很好用的，特别是它对于暴露功能的设计还是有迹可循的，有兴趣可以看看。而 updateCh 是在哪里消费的呢？其实这一点你通过看之前的 k8s 源码应该有所熟悉了，消费的地方正式在启动的时候设置好了。

启动

Start 并不复杂，精简一下如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// internal/ingress/controller/nginx.go:270
func (n *NGINXController) Start() {
    klog.InfoS("Starting NGINX Ingress controller")

    n.store.Run(n.stopCh)
    cmd := n.command.ExecCommand()

    n.start(cmd)

    go n.syncQueue.Run(time.Second, n.stopCh)
    // force initial sync
    n.syncQueue.EnqueueTask(task.GetDummyObject("initial-sync"))

    for {
        select {
        case err := <-n.ngxErrCh:
            if n.isShuttingDown {
                return
            }

            // if the nginx master process dies, the workers continue to process requests
            // until the failure of the configured livenessProbe and restart of the pod.
            if process.IsRespawnIfRequired(err) {
                return
            }

        case event := <-n.updateCh.Out():
            if n.isShuttingDown {
                break
            }

            if evt, ok := event.(store.Event); ok {
                klog.V(3).InfoS("Event received", "type", evt.Type, "object", evt.Obj)
                if evt.Type == store.ConfigurationEvent {
                    // TODO: is this necessary? Consider removing this special case
                    n.syncQueue.EnqueueTask(task.GetDummyObject("configmap-change"))
                    continue
                }

                n.syncQueue.EnqueueSkippableTask(evt.Obj)
            } else {
                klog.Warningf("Unexpected event type received %T", event)
            }
        case <-n.stopCh:
            return
        }
    }
}

我们刚才的关键 updateCh 就在这里，event := <-n.updateCh.Out()，从中获得对应的事件然后放到 syncQueue 里面，而 syncQueue 则是我们在 NewNGINXController 的时候初始化的

1

n.syncQueue = task.NewTaskQueue(n.syncIngress)

所以最终就落到了 syncIngress 方法上：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// internal/ingress/controller/controller.go:175
func (n *NGINXController) syncIngress(interface{}) error {
    n.syncRateLimiter.Accept()

    ings := n.store.ListIngresses()
    hosts, servers, pcfg := n.getConfiguration(ings)

    if n.runningConfig.Equal(pcfg) {
        klog.V(3).Infof("No configuration change detected, skipping backend reload")
        return nil
    }

    n.metricCollector.SetHosts(hosts)

    if !utilingress.IsDynamicConfigurationEnough(pcfg, n.runningConfig) {
        klog.InfoS("Configuration changes detected, backend reload required")

        hash, err := hashstructure.Hash(pcfg, hashstructure.FormatV1, &hashstructure.HashOptions{
            TagName: "json",
        })
        if err != nil {
            klog.Errorf("unexpected error hashing configuration: %v", err)
        }

        pcfg.ConfigurationChecksum = fmt.Sprintf("%v", hash)

        err = n.OnUpdate(*pcfg)

        klog.InfoS("Backend successfully reloaded")
        n.metricCollector.ConfigSuccess(hash, true)
        n.metricCollector.IncReloadCount()

        n.recorder.Eventf(k8s.IngressPodDetails, apiv1.EventTypeNormal, "RELOAD", "NGINX reload triggered due to a change in configuration")
    }

   // ...

    return nil
}

然后让我们把目光聚到 err = n.OnUpdate(*pcfg)（一开始我压根没注意这个部分，也是仔细寻找才发现了）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

func (n *NGINXController) OnUpdate(ingressCfg ingress.Configuration) error {
    cfg := n.store.GetBackendConfiguration()
    cfg.Resolver = n.resolver

    // ....

    content, err := n.generateTemplate(cfg, ingressCfg)

    err = n.createLuaConfig(&cfg)

    err = createOpentelemetryCfg(&cfg)

    err = n.testTemplate(content)

    // ....

    err = os.WriteFile(cfgPath, content, file.ReadWriteByUser)

    o, err := n.command.ExecCommand("-s", "reload").CombinedOutput()

    // Reload status checking runs in a separate goroutine to avoid blocking the sync queue
    if workerSerialReloads {
        go n.awaitWorkersReload()
    }

    return nil
}

看到这里其实就很清楚了，首先就是根据 ingress 信息和模板创建对应的配置文件。而生成配置文件所需要的模板是在 rootfs/etc/nginx/template/nginx.tmpl 的位置，而看了模板你也就大概明白了，这不仅是 nginx 的配置吗。

然后发现，这不就是我最常用的 nginx -s reload 命令吗？原来就这样简单。这下，从 k8s 的资源变动到 nginx 配置变化，整个链路就能串起来了。

码后解答

1. ingress-nginx 本身究竟是个什么东西？回答：本质其实就是个 deployment 而已，而整个就是打包了一组 k8s 的各种资源在里面
2. Ingress Controller 是如何监听到 Ingress 资源的变化的？回答：其实就是通过 informer 监听了对应资源变更的事件，并且注册了这些事件对应的处理方法，而 SharedInformer 其实是 client-go 里面的实现。
3. Ingress Controller 是如何将规则转换为实际的负载均衡配置的？回答：关键就是通过这些规则的配置，通过模板来生成的。

总结提升

其实原理上对于 ingress 其实本身并不复杂，而更多的是，我觉得它可以作为我们学习如果制作一个 k8s 扩展组件的一个案例，如何使用 Apiserver，如何处理对应的事件，以及如何操作对应的资源等等，将它作为一个参考确实是不错的选择。

编码上

HandleSigterm

之前在 main 入口的最下面我们看到过下面的代码：

1
2
3

process.HandleSigterm(ngx, conf.PostShutdownGracePeriod, func(code int) {
os.Exit(code)
})

其中的 HandleSigterm 的实现其实非常简单，对于一个小型项目的优雅关闭是一个非常不错的案例，可以直接拿来用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// pkg/util/process/sigterm.go:32
func HandleSigterm(ngx Controller, delay int, exit exiter) {
    signalChan := make(chan os.Signal, 1)
    signal.Notify(signalChan, syscall.SIGTERM)
    <-signalChan
    klog.InfoS("Received SIGTERM, shutting down")

    exitCode := 0
    if err := ngx.Stop(); err != nil {
        klog.Warningf("Error during shutdown: %v", err)
        exitCode = 1
    }

    klog.Infof("Handled quit, delaying controller exit for %d seconds", delay)
    time.Sleep(time.Duration(delay) * time.Second)

    klog.InfoS("Exiting", "code", exitCode)
    exit(exitCode)
}

syncQueue

还有一个 syncQueue 其实也可以简单参考下，它是对于 client-go 里面的 workqueue 的封装，本来其实我觉得 workqueue 的实现已经非常好用了，特别是拿他来做泛型的使用案例特别好，所以比较值得一看，以后很大机会能用上。其中有一个取巧的封装是对于 EnqueueSkippableTask 方法，我一开始还在想什么是 skippable 可以跳过的任务，仔细一看发现其实就是任务的优先级，而当可以 skippable 也就是优先级低的时候，只不过将时间延迟了而已。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// internal/task/queue.go:74
func (t *Queue) enqueue(obj interface{}, skippable bool) {
    if t.IsShuttingDown() {
        klog.ErrorS(nil, "queue has been shutdown, failed to enqueue", "key", obj)
        return
    }

    ts := time.Now().UnixNano()
    if !skippable {
        // make sure the timestamp is bigger than lastSync
        ts = time.Now().Add(24 * time.Hour).UnixNano() // 就只是这样而已
    }
    klog.V(3).InfoS("queuing", "item", obj)
    key, err := t.fn(obj)
    if err != nil {
        klog.ErrorS(err, "creating object key", "item", obj)
        return
    }
    t.queue.Add(Element{
        Key:       key,
        Timestamp: ts,
    })
}

对应到实际使用上，其实就是对于外部的 event 的相应任务可以慢慢处理，而对于文件配置的变动需要立刻做出相应，优先级更高。

AI 带火了向量数据库，来对比几个不同的向量数据库，使用感受和差异，个人非标测试，仅供参考。

• milvus
• pgvector
• qdrant
• elasticsearch

具体每个我就不多介绍了，官网都有

使用场景

正所谓不设定场景的测试和比较都是耍流氓，所以先说明一下使用场景。由于大厂的技术选型往往就直接冲着数据量、扩展性等等方向去了，而这次我们的角度不一样，更贴近与个人用户使用，准备用在个人项目中，并且直接安装在个人电脑上。

• 本来就是单点，不需要考虑什么扩展
• 数据量不大，一个人撑死能有多大的数据
• 使尽可能减少资源占用

安装

全部使用 docker 一把梭，使用的宿主机相同配置，都是足够的。

milvus

其中 attu 是专门用来查看的，默认自带的功能比较少，没法直接操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

version: '3.5'
services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.18
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3

  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9001:9001"
      - "9000:9000"
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.5.5
    command: ["milvus", "run", "standalone"]
    security_opt:
    - seccomp:unconfined
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      start_period: 90s
      timeout: 20s
      retries: 3
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"

  attu:
    container_name: milvus-attu
    image: zilliz/attu:v2.4
    environment:
      MILVUS_URL: milvus:19530
    ports:
      - "7000:3000"
    networks:
      - default

networks:
  default:
    name: milvus

pgvector

pgvector 是 postgresql 的一个插件，所以安装之后需要执行命令去启用

1

$ docker run --name postgresql -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

1
2
3

$ docker exec -it postgresql psql -h 127.0.0.1 -p 5432 -U postgres
psql (17.4 (Debian 17.4-1.pgdg120+2))
Type "help" for help.

1
2
3
4
5

$ postgres=# select * from pg_extension;
  oid  | extname | extowner | extnamespace | extrelocatable | extversion | extconfig | extcondition
-------+---------+----------+--------------+----------------+------------+-----------+--------------
 13569 | plpgsql |       10 |           11 | f              | 1.0        |           |
(1 row)

1
2
3
4
5
6
7
8
9

$ postgres=# CREATE EXTENSION vector;
CREATE EXTENSION

$ postgres=# select * from pg_extension;
  oid  | extname | extowner | extnamespace | extrelocatable | extversion | extconfig | extcondition
-------+---------+----------+--------------+----------------+------------+-----------+--------------
 13569 | plpgsql |       10 |           11 | f              | 1.0        |           |
 16388 | vector  |       10 |         2200 | t              | 0.8.0      |           |
(2 rows)

qdrant

1

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

elasticsearch

1
2
3
4
5
6
7
8

docker run -d \
--name elasticsearch \
    -e "ES_JAVA_OPTS=-Xms2048m -Xmx2048m" \
    -e "discovery.type=single-node" \
    --privileged \
    -p 9200:9200 \
    -p 9300:9300 \
elasticsearch:7.17.7

测试

前提

• 相同的向量数据，是同一个模型 embedding 生成相同的向量数据，维度 1024
• 相同的索引算法， HNSW (Hierarchical Navigable Small World)
• 相同的计算方法，COSINE 余弦相似度

查询速度

小数据量下区别不大，大数据量下这个差距会扩大

• milvus 执行时间：452.41ms
• pgvector 执行时间：180.65ms
• qdrant 执行时间：69.00ms
• elasticsearch 执行时间：314.35ms

CPU

pgvector 的 CPU 波动最不明显，qdrant 和 elasticsearch 相差不大，而 milvus 显然 CPU 敏感，测试多次效果基本一致。

内存

从内存的角度上来说，很明显 elasticsearch 和 milvus 占用更多，而 qdrant 和 pgvector 从图片中很难看出区别，但实际数据值可以看到一个是 172MiB(pgvector) 一个是 152.9MiB(qdrant) 也区别不大。

1
2
3
4
5
6
7
8
9
10
11
12

CONTAINER ID   NAME                CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O         PIDS

4c3b1922b36b   elasticsearch       0.46%     1.619GiB / 5.126GiB   31.59%    378MB / 31.9MB    201MB / 7.75GB    100

1c0febeff728   postgresql          0.00%     172MiB / 5.126GiB     3.28%     1.28GB / 125MB    342MB / 6.08GB    12

58fa2a1d8558   qdrant              1.37%     152.9MiB / 5.126GiB   2.91%     648MB / 9.41MB    291MB / 8.23GB    52

bb05db1d3099   milvus-standalone   6.92%     368.5MiB / 5.126GiB   7.02%     18.9GB / 14GB     776MB / 5.62GB    88
b0c0ff71478e   milvus-attu         0.36%     28.27MiB / 5.126GiB   0.54%     9.66MB / 27.3MB   41.7MB / 96.6MB   23
edad780e6197   milvus-minio        14.68%    133.1MiB / 5.126GiB   2.54%     13.8GB / 18.1GB   18.5GB / 17.5GB   27
fc8e6e0012ae   milvus-etcd         0.53%     30.41MiB / 5.126GiB   0.58%     156MB / 118MB     67.9MB / 12.3GB   15

使用

我使用的 go 连接的每个数据库，具体代码就不展示了，每个仓库的使用方式的各有不同，但好在 sdk 都完整所以直接将官方的案例拷贝过来都能用。说几个实际中遇到的问题。

milvus

相比于其他几个，它的使用需要额外在查询之前 LoadCollection ，需要手动 load 到内存里面去。然后如果使用完之后不用了，可以关掉。

解析结果的时候一定注意查询结果还在内侧，而非最外面

1
2
3
4
5

searchResult, err := m.client.Search(

// 需要两个循环
for i := 0; i < len(searchResult); i++ {
for j := 0; j < searchResult[i].ResultCount; j++ {