网络 on 小盒子的技术分享

Postman 越来越臃肿了，我换了个开源的，还能让 AI 帮我写测试

Mon, 13 Apr 2026 03:56:46 +0000

Postman 我用了好几年了。

从最早的 Chrome 插件时代开始用的，那时候它还是个轻量小工具，打开就能测接口，干干净净。但最近这两年，怎么说呢，它开始「端着」了。

打开就让我登录。不登录不让用。

好不容易登录了，又弹窗让我升级 Team 版。

集合还给我存到云端去了。我就测个本地接口，你把我的请求数据往你服务器上传干嘛？

我一直忍着，直到有一天，团队里两个人同时改了同一个集合，Postman 云同步直接给合并冲突了，还没法像 Git 那样 diff 看变更。那天我就想，不行了，得换。

然后我遇到了 Bruno。

怎么形容呢，就像你一直在用一个越来越臃肿的 IDE，突然有人递给你一个 Vim，告诉你「够用了，而且是你的」。

Bruno 干了一件特别简单但特别对的事情，它把你的 API 请求存成 .bru 文件，放在你本地文件夹里。

就是普通的文本文件，打开长这样。

1meta { name: 用户登录 type: http seq: 1}post { url: {{baseUrl}}/auth/login body: json auth: none}headers { Content-Type: application/json}body:json { { "username": "{{username}}", "password": "{{password}}", "expiresInMins": 30 }}script:post-response { if (res.status === 200) { bru.setVar("authToken", res.body.accessToken); bru.setVar("userId", res.body.id); }}tests { test("登录应该返回 200", function() { expect(res.status).to.equal(200); }); test("响应中应该包含 accessToken", function() { expect(res.body.accessToken).to.be.a("string"); expect(res.body.accessToken.length).to.be.greaterThan(0); }); test("响应中应该包含用户基本信息", function() { expect(res.body.id).to.be.a("number"); expect(res.body.username).to.equal("emilys"); expect(res.body.email).to.be.a("string"); }); test("响应时间应该小于 3 秒", function() { expect(res.responseTime).to.be.lessThan(3000); });}

你看，GET 请求、Header、Body、断言，全都是纯文本。你用任何编辑器都能打开它，改完保存就行。

这玩意最不同的地方在哪？

它可以用 Git 管理。

以前团队共享 Postman 集合，那叫一个痛苦。谁改了什么不知道，版本对不对不确定，冲突了还没法 resolve。

现在用 Bruno，接口定义就是文件，扔进 Git 仓库，该 PR 就 PR，该 Code Review 就 Code Review。有人改了某个接口的 Header，diff 里看得一清二楚。

用程序员已经会的工具，解决程序员的问题。不用学新的协作方式，不用付费，不用担心数据被传到哪个云上。

Bruno 官网上有一句话我印象特别深，大意是**「我们不会同步你的任何数据到云端，甚至连登录的概念都没有。我们看不到你在 Bruno 里输入了什么，也不会用你的数据训练任何 AI 模型」。**

在这个年代，一个工具敢这么说，我觉得还是挺硬气的。

回到工具本身。说到这里，可能有朋友会想，开源 API 客户端一抓一大把，Insomnia、Hoppscotch、Thunder Client，凭什么是 Bruno？

我自己用下来，让我有「这玩意不一样」的瞬间，是发现它有 CLI。

但我说的不是「能在终端里跑测试」这种废话。Newman 也能跑，Postman 自己也有命令行。我说的是另一件事。

Bruno 的 CLI，让 Claude Code 和 Cursor 这种 AI 编程工具，第一次能真正帮你写和跑接口测试。

这话有点大，我用两件刚发生的真事讲一下。

回到 Bruno 的 CLI 本身。装它就一行，

1npm i -g @usebruno/cli

装完之后命令叫 bru，跑整个集合的测试是这样，

1bru run --env production

输出长这样。

干净、彩色、有 ✓ 和 ✗、有总耗时、有失败原因。最重要的是，这是一段普通的终端命令，输出是普通的文本。

为什么这件事重要？因为这两个特征，正好是 AI 编程 agent 工作的边界。

Claude Code、Cursor、Codex 这些工具，它们能干什么？它们能读你的代码文件，能写新的文件，能在终端里跑命令，能读命令的输出。它们不能干什么？它们不能点击 Postman 的按钮，不能在你 GUI 里输入 token，不能登录任何账号。(或者说不方便，成本高，效率低)

Postman 的核心数据存在云端、操作靠 GUI、协作靠登录，这三件事每一件都把 AI agent 挡在外面。

而 Bruno 的核心数据是 .bru 文本文件、操作靠 CLI、协作靠 Git。每一件都正好是 AI 最擅长的那种事。

抽象的说完了，说点具体的。

我前两天就让 Claude Code 帮我加了一个测试，过程是这样的。

我跟它说，「我刚加了一个搜索商品的接口，帮我在 bruno 集合里加个测试用例」。

它干了三件事，全程没问我任何问题。

第一步，读了我现有的一个 .bru 文件，就是为了搞清楚我用的格式。比如我习惯加哪些 test，断言风格是什么样的。

第二步，照着这个格式写了一个新的 06-搜索商品.bru 文件，放在我集合的根目录里。请求方法、URL、query 参数、4 条断言，全都给我加上了。

第三步，它直接执行 bru run 06-搜索商品.bru --env production，亲眼看着 4 个测试全绿，然后才回我一句「写完了，4/4 通过」。

整个过程我没碰 Bruno 的 GUI，没敲一个字符的代码，没解释什么是 .bru 格式。AI 自己读自己写自己跑自己验证。

你可能会问，这个事换成 Postman 不行吗？

我得先把话说清楚，Postman 不是没有 CLI。Newman 一直都在，Postman Collection 也是 JSON 文件，AI 理论上能读能写。这条路是通的。

但你真去试一下就会发现，那条路上全是石头。

Postman 的 Collection JSON 格式不是给人手写的。我做了个最朴素的对比，同一个 GET 请求加一条「状态码等于 200」的断言，写成 .bru 是 15 行，导出成 Postman Collection JSON 是 44 行。区别在哪？.bru 里 URL 就是一个字符串 https://api.example.com/users，Postman JSON 里 URL 被拆成 protocol、host 数组、path 数组三个字段。.bru 里测试代码就是普通 JS，Postman JSON 里测试代码以字符串数组的形式塞在 event 里，每一行 JS 都得加引号、转义、再 JSON 序列化一次。还有一堆 _postman_id、_exporter_id、schema 这种内部元数据，跟你的业务接口毫无关系，但你不写就报错。

让 AI 写 .bru，它跟写 markdown 一样轻松。让 AI 写 Postman JSON，它更像在翻译一份配置文件，token 烧得多，出错概率高，写完你自己 review 都费劲，git diff 出来三行业务变更夹在二十行格式噪音里。

所以不是 AI 不能写 Postman 的测试，是 Postman 的格式从一开始就没打算让人手写，更没打算让 AI 直接读写。它假设你有一个 GUI 在中间帮你管理这些内部细节。AI 进来之后，那个假设就有点尴尬了。

我说的还不是最炸的场景。

真正让我觉得 Bruno + AI 是 1 + 1 大于 10 的，是调试场景。

我又试了一次，让 Claude Code 帮我加一个购物车接口的测试。它写完跑了一遍，挂了。

错误信息是这样的。

 1✕ 购物车应该有 totalPrice 字段 expected undefined to be a number✕ 购物车应该有 products 数组 expected undefined to be an array
 2
 3```bash
 4
 5它猜错了字段名。这种事很正常，毕竟它没真的去看接口返回。但接下来才有意思。
 6
 7它没有问我、没有让我提供文档、也没有放弃。它自己执行了一条 curl 命令，把购物车接口的真实响应拉了下来。
 8
 9```bash
10curl -s https://dummyjson.com/carts/1

看到响应里字段是 total 和 products，不是 totalPrice 和 items。它马上把测试里的字段名改了，再跑一遍，全绿。

整个调试过程，我做了什么？我什么也没做。我只是看着它一步一步跑完。

这就是 Bruno + CLI + AI 的真正价值。你的 API 测试不再是一个孤立的、需要你手动维护的负担，而是变成了 AI 可以读、可以写、可以跑、可以调试的一种代码。

它和你的源码、你的 Git 历史、你的 CI/CD、你的 AI agent，全都是一体的。

写到这里我猜有人要拍桌子了。

「等等，国内程序员谁还用 Postman 啊？Apifox 它不香吗？」

发，我们专门聊聊 Apifox。

我必须先承认它真的很强。一体化平台，API 文档、调试、Mock、自动化测试、团队协作全在一个工具里搞定，相当于 Postman + Swagger + JMeter 三合一。界面是中文，文档是中文，国内团队几乎零学习成本。如果你的团队 20 人以上，需要权限管理、需要实时协作、需要统一的 API 文档管理，Apifox 是比 Bruno 更合适的选择。这点我不否认。

而且 Apifox 不傻，它也在跟上 AI 浪潮。它有 apifox-cli，能在终端里跑测试场景。它甚至专门做了 Apifox MCP Server，可以让 Cursor 和 Claude Desktop 读取 Apifox 项目里的 API 文档，帮你写代码。

那问题来了，Bruno 和 Apifox 在 AI 这件事上到底有啥不一样？

我读了一圈 Apifox 的官方文档，发现一个挺有意思的差别。

Apifox 接 AI 的方式，是让 AI 来连接 Apifox。Bruno 接 AI 的方式，是 Bruno 根本就是 AI 已经会读的格式。

具体说，Apifox 的 AI 工作流是这样的，你的测试数据躺在 Apifox 云端项目里，你装一个 Apifox MCP Server，配置 Cursor 去连这个 MCP，AI 通过 MCP 协议向 Apifox 服务发请求，把 API 文档拿下来，再帮你生成代码。

Bruno 的 AI 工作流是这样的，你的测试就是项目目录里的 .bru 文件，AI 直接 cat、edit、bru run。完了。

你看出区别了吗？Apifox 把 AI 当成一个外部工具来对接，所以需要 MCP 这一层中转。而 Bruno 根本不需要 MCP，因为它跟 AI 用的是同一种原生语言：文本文件加终端命令。

还有一个更现实的差别。Apifox 的 MCP Server 现在的能力，是让 AI 读取 API 文档来生成代码，它并不能让 AI 直接去编辑你的测试用例。AI 在 Apifox 这边的角色基本上是只读的。

而我前面演示的那两个场景，Claude Code 帮我写新测试、自动调试、修字段名，那是完整的读写跑改循环。AI 不光在读，还在写，还在跑，还在调试。这是因为 .bru 是普通文件，Edit 工具就能改，Bash 工具就能跑。它中间没有任何一层，所以也没有任何一层会卡住。

这不是说 Apifox 不好，是两条不同的路。Apifox 选的是「我是平台，AI 来连我」，Bruno 选的是「我什么都不是，我就是文件」。前者适合企业级场景，后者适合代码即测试的开发者工作流。

我自己是后者。我喜欢我所有的东西都能塞进 Git 仓库，喜欢 AI 直接读我硬盘上的文件，不喜欢任何账号、登录、云端中转。所以我选 Bruno。

如果你的工作场景更接近企业级 SaaS 那一套，那 Apifox 完全没问题，甚至更合适。但如果你跟我一样，希望让 AI 一句话把接口测试搞定，那 Bruno 这条路确实更顺。

聊完 Apifox 我们继续。顺便提一下 CI 集成，因为这块也很丝滑。Bruno CLI 支持输出 JUnit XML，GitHub Actions、GitLab CI、Jenkins 直接吃这个格式。我的工作流文件大概长这样。

1- name: 安装 Bruno CLI run: npm install -g @usebruno/cli- name: 跑接口测试 run: bru run --env production --reporter-junit junit.xml

两步。你的 PR 一提交，所有接口测试自动跑一遍，挂了直接拒绝合并。

生成的测试执行也挺好看的

整套东西免费、开源、本地、Git 友好、AI 友好，不用登录、不用付钱、不用担心数据上云。

安装很简单。桌面版，

1brew install bruno
2
3```bash
4
5CLI，
6
7```bash
8npm i -g @usebruno/cli

用了一周之后我把 Postman 卸了。

不是它不好，是我不再需要一个登录才能用、集合存在别人云上、免费版各种限制、AI 完全帮不上忙的接口测试工具了。

我只需要一个文件夹、几个 .bru 文件、一条终端命令，和一个能读懂这一切的 AI。

有时候工具的进步不是功能越加越多，而是把不该有的东西去掉。Bruno 去掉了登录、去掉了云端、去掉了 GUI 锁定，剩下的全是程序员真正需要的东西。

而当你把这些不需要的东西去掉之后，你会发现一个意外的副作用，AI 进来了。

好了就说这么多。

如果你也受够了 Postman，试试 Bruno。说不定你也会像我一样，用完就回不去了。

ps:我写的 demo 在这里，你可以拉下来试一下，可以 run 的：https://github.com/xiaobox/bruno-demo

OpenClaw 爆火背后：它不是聊天机器人，而是一套真正会做事的 AI 系统

Wed, 11 Mar 2026 10:14:30 +0000

如果你最近在 GitHub 上关注过 AI Agent 领域，大概率已经看到过 OpenClaw。到 2026 年 3 月 10 日，它的 GitHub 仓库已经来到约 297k stars，超过了 React 的约 244k 和 Linux 的约 222k。更重要的不是数字本身，而是它火起来的方式：它不是靠一个漂亮网页，也不是靠一个“会聊天的套壳”，而是靠一整套把大模型接入真实消息渠道、真实设备、真实浏览器、真实文件系统的系统架构，硬生生把“AI 助手”做成了一个长期在线的工程系统。

但如果你只把 OpenClaw 理解成“接了很多 IM 的机器人”，你会完全错过它最有价值的部分。OpenClaw 官方 README 写得很直白：“The Gateway is just the control plane — the product is the assistant.” 这句话几乎就是读懂整个项目的钥匙。它的重点从来不是“有多少入口”，而是：有没有一个统一控制面，把消息、状态、路由、模型、工具、节点、权限和安全边界收在一起。 README、架构文档和 Vision 文档都在强调同一件事：OpenClaw 想做的是“真正会做事的 AI”，运行在你的设备、你的渠道、你的规则之内。

这篇文章，我想尽量回答七个问题：

1.它到底是什么？

2.它为什么会采用现在这套架构？

3.Gateway 到底在系统里扮演什么角色？

4.Agent 是怎么运行起来的？

5.Memory、Workspace、Session 为什么是它的关键设计？

6.多 Agent、节点、工具体系是怎么拼到一起的？

7.以及最后，为什么它值得被看作下一代 AI 助手的典型系统样本。

在回答这些问题之前，我不得不说，现在龙虾有些过热了，对于想 “卖铲子” 的公司当然觉得这是好事，于是他们推波助澜，但对于专业人士不能人云亦云。openClaw 有它优秀的一面，也有被炒作夸大的一面，应该客观地看。

一、OpenClaw 的本质，不是聊天机器人，而是“个人 AI 助手控制面”

一句话定义 OpenClaw，我会这样说：

OpenClaw = 一个以 Gateway 为中心的个人 AI 助手控制平面，下面挂着嵌入式 agent runtime、会话系统、工具系统、消息渠道、节点设备和安全边界。

这个定义不是我自己拔高出来的，而是官方文档本身就在往这个方向写。

●README 说它是“你运行在自己设备上的 personal AI assistant”；

●架构文档说它是一个 single long-lived Gateway，拥有所有 messaging surfaces；

●Vision 文档则把它描述为“the AI that actually does things”，运行在你的设备、你的渠道、你的规则里。

把这些信息放在一起看，你会发现 OpenClaw 的设计起点根本不是一个“聊天 UI”，而是一个长期在线、可被多入口触发、可调用工具、可连接设备、可持续维护状态的 AI 系统。

这也是为什么我认为 OpenClaw 更接近“控制面”而不是“应用层”。在很多 AI 产品里，用户打开网页，输入问题，后端调一下模型，返回一段文本，交互就结束了。OpenClaw 则完全不是这种形态。它默认有一个长期运行的 Gateway 进程，消息渠道接到这个 Gateway，上层的 CLI、Control UI、WebChat 接这个 Gateway，macOS/iOS/Android/headless 节点也接这个 Gateway，甚至定时任务、exec approvals、pairing 和 health 事件都围绕 Gateway 展开。也就是说，Gateway 不是一个消息转发器，而是系统中枢。

二、Gateway 为什么是 OpenClaw 最关键的设计

OpenClaw 官方架构文档里最重要的一句话，是它把 Gateway 明确成 single control plane。一个长期运行的 Gateway 拥有所有 messaging surfaces；control-plane clients 通过 WebSocket 连进来；nodes 也通过 WebSocket 连进来，但会声明自己是 role: node；Canvas host 也由 Gateway 的 HTTP server 提供，而且默认和 Gateway 共用 127.0.0.1:18789 这个端口。

这意味着什么？意味着 OpenClaw 的系统设计不是“每个端各做一套逻辑”，而是“先做一个统一控制面，再让所有端接入它”。这在工程上有三个非常大的好处。

第一，状态是统一的。

会话在哪里维护？在 Gateway。

路由在哪里决策？在 Gateway。

设备配对、认证 token、事件广播、健康状态、cron、工具审批在哪里收敛？还是在 Gateway。

这让系统不会因为前端入口变多而出现多套状态、多个事实来源。

第二，协议是统一的。

Gateway protocol 文档明确写了：OpenClaw 不是“随便传一段 JSON”，而是有明确握手流程和版本约束的 WebSocket 协议。服务端先发 connect.challenge，客户端再带着 device identity、role、scopes、caps、auth、签名等参数发起 connect，通过后才返回 hello-ok。协议版本有 minProtocol/maxProtocol 协商，协议 schema 由 TypeBox 定义，再生成 JSON Schema 以及 Swift model。对一个跨 CLI、网页、桌面、移动端、节点设备的系统来说，这种 typed protocol 的价值非常高。

第三，能力是统一暴露的。

比如 Control UI 不是一个独立后端，而是 Gateway 在同一端口上提供的浏览器管理界面；WebChat 直接连 Gateway WebSocket；nodes 也不是第二套服务，而是带 role:node 的外围设备。也就是说，OpenClaw 并不是“一个 App + 一堆外挂”，而是“一个控制面 + 多个表面”。

很多人第一次看 OpenClaw，会把注意力放在“它居然支持这么多渠道”。但真正懂架构的人，会先看 Gateway。因为能不能把多个入口、多种设备、多条事件流、多种工具执行方式，全都压到一个长期运行的控制面里，决定了它到底是“一个功能”还是“一个系统”。OpenClaw 的做法很明确：先有控制面，再有助手。

三、它最强的抽象，不是对话框，而是 Agent、Session 和 Route

很多 AI 产品最基础的抽象单位是“聊天窗口”。OpenClaw 不是。

OpenClaw 的真正基础模型，是：

●谁来回复（Agent）

●回复落在哪段连续上下文里（Session）

●一条消息应该被路由到哪个 agent 和哪个 session（Route）

Agent：一颗完整隔离的大脑

Multi-Agent 文档里写得很清楚：一个 agent 是一个 fully scoped brain，拥有

●自己的 workspace

●自己的 agentDir

●自己的 auth profiles

●自己的 session store

它的文件、人格、配置、认证信息和会话历史都是围绕这个 agent 单独组织的。默认路径也很清晰：

●workspace 在 ~/.openclaw/workspace 或 workspace-<agentId>

●session 存在 ~/.openclaw/agents/<agentId>/sessions

●auth profile 在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

这件事非常重要。因为这说明 OpenClaw 的多 Agent，不是“在一个上下文里换不同 system prompt 假装多人格”，而是真的把状态、身份、凭证和工作目录做成了隔离单元。但要注意，这种独立是为了让系统跑得更有条理，属于“防君子不防小人”的内部隔离。官方的意思很明确：同一个网关（Gateway）里的 Agent 默认都是“自己人”，不能把互不信任、甚至带有敌意的任务强行塞进同一个网关里，它并没有提供那种级别的安全防御。

Session：上下文连续性的主键

Session 文档里有一句特别关键的话：

OpenClaw treats one direct-chat session per agent as primary.

这句话可以理解成：对每一个 agent，OpenClaw 都认为它有一个“主私聊会话”

OpenClaw 默认会将一个 Agent 接收到的所有私聊（Direct Message, DM）都汇聚到一个主会话里（即 agent:<agentId>:<mainKey>）。对于群聊、频道或特定的话题（Thread），则会自动拆分独立处理。

对于 direct chat， agent 有一个规范意义上的主会话；默认所有 DM 都往这里归并，以保证连续性。

假设你有一个 agent 叫 main。默认情况下：

●你在 Web UI 私聊它一次

●之后又在 CLI 私聊它

●再后来在手机端私聊它

如果这些都被识别为 direct chat，而且你没有改 session.dmScope，那么这些私聊会折叠进同一个主 session,这样做的好处是：agent 会把这些私聊视为同一条连续对话，而不是三个彼此割裂的会话。

默认的主会话机制在单用户场景下很完美，但在多用户场景下就是一个巨大的安全漏洞。

如果 Alice 和 Bob 都去私聊同一个 Agent，在默认配置下，他们实际上是在向同一个“上下文沙箱”里写入数据。这就好比两个人共用一个日记本：

●Alice 刚和 Agent 聊完财务密码。

●Bob 接着去问 Agent“我们刚才聊了什么？”

●Agent 就会直接把 Alice 的密码复述给 Bob，造成严重的信息泄露。

为了应对多用户场景，OpenClaw 提供了 session.dmScope 配置，允许你在架构层面把私聊的上下文切分成更安全的细粒度：

●按发信人隔离（per-peer）。

●按频道+发信人隔离。(per-channel-peer)

●按账号+频道+发信人隔离(per-account-channel-peer)。

⚠️ 如果你在开发面向多用户的 AI Agent，绝对不能盲目使用默认的私聊配置。必须根据业务需求，通过调整 dmScope 将用户的对话状态彻底隔离开，防止你的 Agent 变成一个没有隐私边界的“大喇叭”。

Route：决定消息进入哪颗大脑

Channel Routing 文档把消息路由规则写得非常明确，一条消息发过来，绝对不是“哪个 Agent 闲着就扔给谁”，而是像网关（Gateway）匹配规则一样，必须严格按照优先级一层层往下筛，直到找到唯一确定的接收者。

我们可以用**“公司收发室分拣快递”**来打个比方，看一下这 5 层降级（Fallback）匹配规则：

1.精准单聊 (Exact peer match)：快递单上写着“直接交到张三本人手里”。

○明确的点对点直接交互，优先级最高。

2.跟帖/线程继承 (Parent peer match)：快递单没写名字，但备注了“这是昨天那个加急件的补充材料”。收发室一查昨天是李四负责的，直接给李四。

○识别 Thread 或上下文，让同一个 Agent 连贯处理同一个话题。

3.平台级群组与角色 (Discord guild+roles / Slack team)：快递写着“给财务部经理”或“给核心开发组”。

○根据外部平台（如 Discord/Slack）的特定权限组或大团队来分配对应的 Agent。

4.账号与频道 (Account / Channel)：快递写着“送到 3 楼会议室”或“交给官方客服号”。

○匹配特定的聊天频道或绑定的公共账号。

5.默认兜底 (Default agent)：啥也没写清楚的无主件，统统扔给“前台总机”处理。

○如果上面所有条件都未命中，最后由默认的 Agent 统一接管。

这意味着 OpenClaw 的“消息归属”不是模糊的。一条消息不是“谁在线谁回”，而是经过一套确定性规则，先判定该由哪个 agent 接管，再决定落到哪个 session 里。

所以 OpenClaw 能天然处理这些现实世界场景：

●同一个 Gateway 托管多个 agent；

●一个 Telegram 群给 work agent；

●一个 WhatsApp 家庭群给 family agent；

●一个 Slack team 给 support agent；

四、Agent 不是外挂调用，而是嵌入式运行时

很多人对 OpenClaw 最大的误解，是把它当成了一个简单的“任务调度员”——以为它只是在收到消息时，拉起一个外部的子进程（Subprocess）去跑一下，或者通过接口（RPC）远程调一下就完事了。

但架构文档明确指出：OpenClaw 是将 Agent 运行时“原生内嵌”到自己的网关里的。它不是把 Agent 当作一个不可控的外部黑盒，而是直接在内部实例化 Agent 的核心会话（AgentSession）。

Pi Integration Architecture 文档写得非常明确：OpenClaw 不是把 pi 作为 subprocess 或 RPC mode 的外部黑盒去调用，而是直接导入并实例化 pi 的 AgentSession，通过 createAgentSession() 把 agent runtime 嵌入到自己的消息网关架构里。

这种“深度内嵌”的架构设计，直接赋予了系统 6 大核心优势：

1.全局生命周期掌控：从对话的创建、挂起、恢复到销毁，网关层拥有绝对的控制权。

2.动态能力扩展：可以在运行时，随时把自定义的外部工具“塞”给 Agent 使用。

3.“看人下菜碟”的人设：能够根据消息来源（不同的平台渠道或上下文），动态切换 Agent 的系统提示词。

4.强悍的记忆管理：不仅能持久化保存对话，还支持高级的“记忆压缩（Compaction）”防止上下文爆满，甚至支持像 Git 一样对对话“开分支（Branching）”。

5.智能凭证轮询：在多个账号或 API Key 之间自动无缝切换，轻松应对并发和限流问题。

6.模型厂商解绑：底层的大模型想换就换，完全不受单一服务商（如 OpenAI、Anthropic）的绑架。

简单来说，OpenClaw 走的是“直接收编”的路线，它把 Agent 的核心大脑直接“拔”过来，原生种植在了自己的神经中枢里。这就好比你不再是打电话咨询外部专家，而是直接把这位专家招进了自家的核心指挥部。正因为“人”彻底成了内部员工，你才能拥有上帝视角般的掌控力：你可以全面接管他的作息安排（会话生命周期），随时往他手里塞各种定制兵器（动态注入工具），根据不同场合要求他扮演不同的角色（按渠道切换提示词），像操作代码仓库一样去整理甚至分叉他的记忆（支持压缩与分支的持久化），甚至连他背后的“脑力供应商”（随时无缝切换各家大模型）和权限账号，都能在底层悄无声息地替他自动轮换。说白了，OpenClaw 不是在和 Agent “跨部门合作”，而是直接把 Agent 融为了自己身体的一部分。换句话说，OpenClaw 不是“在用一个 agent”，而是“在拥有一个 agent runtime，并把它纳入自己的控制面”。这也是它跟很多“外接 Agent SDK 的应用层产品”最大的差别之一。别人只是调用，OpenClaw 是接管。

五、Agent Loop：一条消息的"真实旅程"

前面我们讲了 Gateway 如何把消息路由到正确的 Agent。现在让我们跟随一条消息，看看它进入 OpenClaw 后，到底经历了什么。

不是"一次请求"，而是一个完整生命周期

如果你习惯了网页聊天框的"发消息→等回复"模式，OpenClaw 的处理方式会让你有点意外。

传统模式：

⚡ 代码片段用户发消息 → 后端调用模型 → 返回文本 → 结束

OpenClaw 模式：

⚡ 代码片段用户发消息 → 分配 runId → 解析 session → 装配上下文 → 运行 agent → 流式返回事件 → 持久化 session → 结束

这一条链路，实际上就是你给 OpenClaw 发一句话之后，系统内部真实发生的事情。它不是“一次 HTTP 请求”，而是一个完整的运行生命周期。

OpenClaw 把你的消息视为一个进程而非请求。它会给这个进程分配ID、监控生命周期、管理并发、持久化状态。

并发控制：为什么同一聊天窗口的消息要"排队"？

想象一下这个场景：你在 Telegram 连续发了三条消息：

●“帮我查一下明天天气”

●“顺便看看日程”

●“把第一封邮件标为已读”

如果这三条消息并发执行，会发生什么？

●Agent 可能先处理了邮件，再处理天气

●Session 历史会乱序写入

●工具调用可能互相冲突

OpenClaw 的解决方案很简单：每个 session 串行化执行。这不是性能问题，而是状态一致性问题。长期在线的助手，必须保证"记忆"不会被乱序操作搞乱。是防止工具竞争和状态污染的工程必要选择。

流式事件：你看到的不是"打字动画"，而是真实的工作过程

OpenClaw 的流式输出，不是简单的"逐字显示"，而是三种事件流：

为什么要这样设计？因为这让用户能真正"看到 AI 在工作"。不是动画，不是假进度条，而是系统内部真实发生的事件被推送到前端。它的体验更像一个"正在办公的助手"而非"死寂的输入框"

六、真正让它“像一个人”的，不是模型，而是 Workspace、System Prompt 和 Memory

很多人体验 OpenClaw 后会有一种明显感觉：它比普通网页聊天更像一个“持续存在的助手”。这种感觉，核心不是来自模型，而是来自它对工作区、提示词和记忆的系统化设计

Workspace：AI 的家，而不是一个临时目录

简单说，Workspace 就是 AI 的"家"：

●它有固定的位置（~/.openclaw/workspace/）

●它有固定的文件结构

●它是 AI 长期工作的地方，不是临时落脚点

OpenClaw 在 Workspace 里约定了一整套"说明书文件"：

这个设计特别妙。因为它把很多系统会偷偷塞进 prompt 模板或数据库里的东西，变成了用户可见、可读、可改、可备份的文件系统资产。你不是在“配一个人设”，而是在维护一个 AI 的长期工作环境。

这里有一个非常重要的提醒：workspace 是默认工作目录，但不是硬沙箱（hard sandbox）；相对路径默认在 workspace 内解析，但绝对路径仍可能访问宿主机其它位置，除非你开启 sandbox。

System Prompt：每次运行都在"编译上下文"

OpenClaw 不是把用户的问题直接扔给模型，而是每次都重新构建一份完整的上下文：

1⚡ 代码片段System Prompt 结构：
2├── Tooling（可用工具列表）
3├── Safety（安全规则）
4├── Skills（技能列表）
5├── Workspace Context（工作区文件）
6├── Documentation（相关文档）
7├── Current Date & Time（当前时间）
8└── Runtime（运行环境信息）

Context 文档还补充了细节：默认会把 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md 等文件作为 Project Context 注入系统提示；技能本身只会注入“技能列表和描述”，真正的 SKILL.md 需要模型按需读取。

类比：

●传统聊天：像"临时起意打电话"

●OpenClaw：像"开会前先发会议议程和背景资料"

Memory：真正写到磁盘，才算记住

Memory 文档里我最喜欢的一句话是：

The files are the source of truth; the model only “remembers” what gets written to disk.

OpenClaw 默认的记忆结构非常简单，但非常工程化:

1⚡ 代码片段workspace/
2 ├── memory/
3 │ ├── 2026-03-10.md ← 今天的日志
4 │ ├── 2026-03-09.md ← 昨天的日志
5 │ └── ...
6 └── MEMORY.md ← 长期、精炼的永久记忆

两种记忆的区别：

检索机制：不是"只有文件"，也不是"只有向量"

OpenClaw 使用混合检索,它明确暴露了两个 agent-facing tools：

●memory_search 负责检索

●memory_get 负责精确读取某个 Markdown 文件或行段

1⚡ 代码片段用户问"我上次出差去哪了？"
2 ↓
3 BM25 关键词检索 ← 精确匹配"出差"
4 +
5 向量语义检索 ← 理解"去哪了"是问目的地
6 ↓
7 MMR 重排序 ← 去重、多样化
8 ↓
9 返回最相关的几条记忆片段

记忆刷新：在"遗忘"前先"存档"

OpenClaw 有一个很巧妙的设计：pre-compaction memory flush

当 session 接近上下文上限（比如对话太长，快塞不进模型窗口了），OpenClaw 会：

●触发一次"静默回合"（用户看不到）

●提醒模型：“把值得记住的信息写入记忆文件”

●然后再压缩上下文

七、工具体系：分层设计，不是堆砌功能

如果说 Gateway 是控制面，Session 是状态骨架，那么 Tools / Plugins / Skills 就是 OpenClaw 的执行肌肉。

OpenClaw 的工具体系有三个层次，很多人会混淆。让我们分清楚：

Tools：第一等公民

OpenClaw 暴露的是 first-class agent tools，不是外挂脚本。包括 browser、canvas、nodes、cron、gateway、session 相关工具、agents_list、image、pdf、message、exec 等。

OpenClaw 没有把“能力调用”做成 prompt 技巧，而是做成了运行时契约。Tool list 和 tool schema 会进入模型上下文；tool allow/deny、tool profiles、per-agent 工具策略、provider-specific 工具策略和 sandbox 工具策略共同决定模型实际能拿到哪些工具

Plugins：扩展系统本身

插件是运行在 Gateway 内部的代码模块，可以：

●注册新的 RPC 方法

●添加新的 HTTP 路由

●注册新的工具

●启动后台服务

类比：

●Skills：像"使用说明书"

●Tools：像"内置功能"

●Plugins：像"给系统装新器官"

Skills：教 AI 如何做事

每个 Skill 就是一个目录，核心是 SKILL.md——一份详细的操作指南。Skill 的三个来源（优先级从高到低）：

●<workspace>/skills/：当前工作区专属

●~/.openclaw/skills/：用户私有技能

●Bundled skills：系统内置技能

与Plugins的本质区别:Plugins是给手机增加新硬件（如外接摄像头）；Skills是相机APP里的"夜景模式"说明书。

八、Node：让 AI “有手有眼”

OpenClaw 严格区分了两个概念：

为什么这样设计？

如果把它们混在一起：

●Telegram Bot 只能干 Telegram 允许的事

●WhatsApp Bot 只能干 WhatsApp 允许的事

每个渠道都要重新实现一遍"控制电脑"的能力

OpenClaw 的设计：

●所有消息渠道都汇聚到 Gateway

●所有设备能力也汇聚到 Gateway

Gateway 负责调度：“这个 Telegram 消息需要控制 iPhone，我来协调”

Node 是什么？

node 是 companion device，可以是 macOS、iOS、Android 或 headless 设备；它通过和 operator 一样的 Gateway WebSocket 接入，但使用 role: “node”，向 Gateway 暴露一组命令面，比如 canvas.、camera.、device.、notifications.、system.*，再由 node.invoke 触发。官方还特别强调：nodes are peripherals, not gateways。消息还是落在 Gateway，不是落在 node

Node 是一台"伴侣设备"，它：

●通过 WebSocket 连接到 Gateway

●向 Gateway 暴露一组能力（camera、notifications、system…）

●等待 Gateway 的指令

类比：

●Gateway：大脑

●消息渠道：耳朵和嘴

●Node：手和脚

没有 Node 的话：

●Telegram Bot 无法直接控制你的 iPhone

●需要你自己手动截图,再发给 Bot

●AI 无法真正"替你做事"

有了 Node：

●AI 可以跨设备协同工作

●你在 Telegram 发指令,它在你的 Mac 上执行

●真正的"个人助手"体验

九、安全边界：诚实比承诺更重要

OpenClaw 的安全模型假设的是 one trusted operator boundary per gateway

OpenClaw 的安全文档非常诚实，这句话翻译成人话是：

这意味着：如果你把Gateway密码给朋友，让他也连进来，你们的对话历史、文件访问、记忆内容默认不隔离。这不是漏洞，是设计选择——为了简化架构，OpenClaw牺牲了多租户隔离，换取单用户场景下的极致能力。

安全层次

 1⚡ 代码片段外层：公网/外部消息源
 2 ↓
 3第一道门：Gateway 入口保护
 4 - token/password 认证
 5 - challenge 签名验证
 6 - device identity 校验
 7 - pairing 审批
 8 ↓
 9第二道门：权限控制
10 - operator / node 角色
11 - scopes 权限范围
12 ↓
13第三道门：执行保护
14 - tool policy（工具策略）
15 - exec approvals（执行审批）
16 - sandbox（沙箱隔离）
17 - allowlist（白名单）
18 ↓
19内层：高风险边界
20 - plugins = trusted code
21 - 插件和 Gateway 同等权限

Sandbox：可以隔离，也可以放行

OpenClaw 的沙箱设计非常灵活：

配置维度：

●mode：off / non-main / all（是否启用沙箱）

●scope：session / agent / shared（沙箱范围）

●workspaceAccess：none / ro / rw（工作区访问权限）

实际用法举例：

浏览器隔离：不是接管你的 Chrome

OpenClaw不会接管你的日常Chrome（那里面可能有银行登录态），而是拉起独立的Chrome Profile：

●独立的Cookie、缓存、扩展

●Agent专用，与你的个人浏览数据隔离

●支持截图、点击、PDF生成，但无法访问你个人的浏览器历史

这是"能力"与"安全"的折中：AI需要浏览器自动化，但不能拥有你的全部数字生活。

十、为什么这是"个人AI操作系统"的雏形？

OpenClaw 之所以值得研究，不是因为它 GitHub stars 多，而是因为它回答了一个未来会越来越重要的问题：

如果 AI 不再是网页对话框，而是一个长期在线、能操作设备、能记住一切的助手，它的系统架构应该长什么样？

OpenClaw 的答案是：

这套答案不一定是终局，也还远没到“完美”。Vision 文档自己都说，项目还很早，当前重点依然是 security、safe defaults、bug fixes、stability 和 setup reliability。也就是说，它依然在快速迭代，仍然带着实验性。

但它已经足够有代表性。因为它第一次比较完整地把“个人 AI 助手”这件事，从概念拉成了系统工程：

●消息不再只是消息，而是事件入口；

●模型不再只是回答器，而是运行时里的推理核心；

●工具不再只是 function calling 演示，而是被策略、审批和沙箱约束的系统调用；

●记忆不再只是“模型好像记得”，而是落到磁盘、可检索、可审计、可 Git 备份的工作区资产

它具备了"操作系统"的味道

不是说它替代 Windows 或 macOS，而是说它有那种系统级的感觉：

1⚡ 代码片段传统应用：打开 → 用 → 关闭
2操作系统：开机 → 长期运行 → 管理所有应用 → 关机
3
4传统 AI：聊天 → 结束
5OpenClaw：启动 Gateway → 长期在线 → 管理所有 Agent → 关闭

最后，再强调一次：OpenClaw 的本质，不是一个接了很多渠道的聊天 Bot，而是一套以 Gateway 为控制面、以 Agent/Session/Memory 为状态骨架、以工具与节点为执行面，把大模型真正接入现实世界的个人 AI 助手系统。

嘿，朋友，做了个 AI 模型比价工具，想请你来试试

Thu, 22 Jan 2026 07:51:40 +0000

大家好，我是小盒子。

这两年 AI 大模型卷得厉害，GPT-4、Claude、Gemini、Llama……模型眼花缭乱，价格也是五花八门。作为一个经常要调用 API 的开发者，我经常想搞清楚一个问题：到底谁家的模型便宜？性价比高的是哪个？

说实话，每次想比较价格，我都得打开一堆浏览器标签页：AWS Bedrock 的定价页、Azure OpenAI 的价格表、OpenAI 官网、还有 OpenRouter……然后手动对比，算汇率，头都大了。更要命的是，这些价格还时不时更新，上周看的数据，这周可能就变了。

不知道你有没有同感：

●想用 Claude 3.5 Sonnet，但不确定是直接调 Anthropic 便宜，还是走 AWS Bedrock 便宜？

●项目预算有限，想找个便宜点的模型先跑通，但不知道该选谁？

●跟老板汇报要说清楚模型成本，却发现各家的计价单位都不一样，有的按 1K tokens，有的按 1M tokens，换算起来很麻烦？

就因为这些"痛点"，前段时间，我干脆撸起袖子，做了一个工具来解决这个问题。

于是，Model Price 就这么诞生了。

它的目标很简单：把各大 AI 服务商的模型价格聚合到一起，让你一眼就能看清谁便宜、谁贵、性价比如何。

代码都在这儿了，开诚布公，欢迎随时来坐坐：

●GitHub: https://github.com/xiaobox/model-price

●在线演示: https://modelprice.boxtech.icu

（要是觉得还行，顺手点个 Star，就是对我最大的肯定。）

这把"锤子"，我花了些心思去打磨

我不想只做个"能看"的工具，我希望它能"好用"，甚至让你"爱用"。所以，在几个关键的地方下了功夫。

首先，数据要全

目前 Model Price 覆盖了 6 家主流 AI 服务商，580+ 个模型：

服务商	模型数量	数据来源
AWS Bedrock	96+	公开 API
Azure OpenAI	50+	零售价格 API
OpenAI	53+	官网爬虫
Google Gemini	31+	官网爬虫
OpenRouter	339+	公开 API
xAI (Grok)	12+	官方文档

无论你用的是 GPT-4、Claude 3.5、Gemini Pro 还是 Llama，都能在这里找到对应的价格。

其次，数据要准

最让我头疼的就是价格变动。所以我给 Model Price 做了自动数据获取机制：

●对于有公开 API 的服务商（如 AWS、Azure、OpenRouter），直接调接口拿最新数据

●对于没有 API 的服务商（如 OpenAI、Google），用 Playwright 爬虫自动抓取官网定价

这样一来，数据基本能保持实时更新，你不用再担心看到的是过时信息。

查找要快

580+ 个模型，如果只能翻页查看，那体验也太差了。所以我加了多维度筛选：

●按提供商筛选：只看 OpenAI 的？只看 AWS 的？一键切换

●按模型系列筛选：只看 GPT-4 系列？只看 Claude 系列？

●按能力标签筛选：支持视觉的？支持音频的？支持 Function Call 的？

●按价格排序：从低到高、从高到低

基本上，三秒内就能找到你想要的模型。

最后，看着要舒服

我做了两种视图模式：

●卡片视图：信息展示更直观，适合浏览

●表格视图：数据更紧凑，适合对比

每个模型的价格还有一个小的柱状图，让你一眼就能看出谁贵谁便宜。输入输出价格分开展示，Batch API 价格也有，该有的都有。

技术栈，给爱折腾的朋友参考

Model Price 的技术选型很主流，方便大家二次开发：

后端：

●Python 3.11+

●FastAPI（高性能异步框架）

●Playwright（网页爬虫，用于抓取 OpenAI、Google 官网）

●httpx（异步 HTTP 客户端）

●uv（超快的 Python 包管理器）

前端：

●React 18

●TypeScript 5

●Vite（构建工具）

●CSS Variables（主题系统）

代码结构清晰，Provider 采用插件架构，想要接入新的服务商，只需要实现一个 BaseProvider.fetch() 方法就行。

这只是个开始

想邀请你一起来添砖加瓦

现在 Model Price 已经能用了，但它离"完美"还差得很远。一个人的力量终究有限，一个好的开源项目，生命力在于社区。

所以，我诚心地邀请你，无论你是谁，都可以来参与这件事：

●如果你只是想找个工具查价格：欢迎直接访问 https://modelprice.boxtech.icu 使用。如果能顺手在 GitHub 上点个 Star，我会非常开心。

●如果你经常用某个服务商，发现数据有误：欢迎提 Issue 告诉我，我会尽快修复。

●如果你和我一样，是个爱折腾的开发者：欢迎来读源码，提 PR。比如接入新的服务商、优化爬虫逻辑、改进 UI 交互……都非常欢迎。

●如果你有其他想法：比如想要对比历史价格、想要价格变动提醒、想要导出 Excel……都可以提 Issue，我们一起讨论。

一个优秀的开源项目，就像一场漫长的篝火晚会，需要不断有人添柴，才能一直燃烧下去。

Model Price 就是我点起的第一根火柴。

好了，就说这么多。感谢你耐心听我这个老家伙唠叨。

如果你对 Model Price 有一点点兴趣，就去看看吧。期待在 GitHub 上，看到你的身影。

GitHub 传送门： https://github.com/xiaobox/model-price

快速安装 ClickHouse

Thu, 17 Jul 2025 09:33:05 +0000

概述

我们使用 docker compose 来安装 ClickHouse

但我们不是裸装 ClickHouse，实际上我们安装的是 ClickStack。有点儿像 elastic-stack 与 elastic search 的关系，但并不完全一样。

ClickStack 是基于 ClickHouse 构建的完整观察性平台，集成了日志、指标、追踪和会话回放功能，提供统一的用户界面和查询能力。因此，ClickStack 是在 ClickHouse 的基础上，结合 HyperDX 提供的前端界面和 OpenTelemetry Collector 实现的完整解决方案。它不仅仅是一个数据库，而是一个集成的观察性平台。

安装步骤参考官方文档：https://clickhouse.com/docs/zh/use-cases/observability/clickstack/getting-started?loc=use-case-observability

安装

克隆 HyperDX 仓库

1git clone https://github.com/hyperdxio/hyperdx.git
2
3cd hyperdx
4
5# switch to the v2 branch
6git checkout v2

根据自身情况修改配置文件 .env

我将 HDX_IMAGE_REPO=docker.hyperdx.io 修改为 HDX_IMAGE_REPO=docker.io 不然镜像拉不下来

 1# Used by docker-compose.yml
 2HDX_IMAGE_REPO=docker.hyperdx.io
 3IMAGE_NAME=ghcr.io/hyperdxio/hyperdx
 4IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx
 5LOCAL_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-local
 6LOCAL_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-local
 7ALL_IN_ONE_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-all-in-one
 8ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-all-in-one
 9OTEL_COLLECTOR_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-otel-collector
10OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-otel-collector
11CODE_VERSION=2.0.5
12IMAGE_VERSION_SUB_TAG=.0.5
13IMAGE_VERSION=2
14IMAGE_NIGHTLY_TAG=2-nightly
15IMAGE_LATEST_TAG=latest
16
17# Set up domain URLs
18HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
19HYPERDX_APP_PORT=8080
20HYPERDX_APP_URL=http://localhost
21HYPERDX_LOG_LEVEL=debug
22HYPERDX_OPAMP_PORT=4320
23
24# Otel/Clickhouse config
25HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

docker compose 启动

1docker-compose up -d

Docker-compose 文件如下：

 1name: hdx-oss
 2services:
 3 # ONLY USED FOR DEMO SSL SETUP
 4 # nginx:
 5 # image: nginx:1.27.3
 6 # volumes:
 7 # - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
 8 # - ./docker/nginx/ssl:/etc/nginx/ssl
 9 # - .volumes/nginx_logs:/var/log/nginx
10 # ports:
11 # - 80:80
12 # - 443:443
13 # networks:
14 # - internal
15 # depends_on:
16 # - app
17 db:
18 image: mongo:5.0.14-focal
19 volumes:
20 - .volumes/db:/data/db
21 # WARNING: Exposing the database port will make it accessible from outside the container,
22 # potentially allowing unauthorized access. If you uncomment the ports below,
23 # ensure to secure your database (e.g., with strong authentication, proper network rules, and firewalls).
24 # ports:
25 # - 27017:27017
26 networks:
27 - internal
28 otel-collector:
29 image: ${HDX_IMAGE_REPO}/${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
30 environment:
31 CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s'
32 HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
33 HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
34 OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
35 ports:
36 - '13133:13133' # health_check extension
37 - '24225:24225' # fluentd receiver
38 - '4317:4317' # OTLP gRPC receiver
39 - '4318:4318' # OTLP http receiver
40 - '8888:8888' # metrics extension
41 restart: always
42 networks:
43 - internal
44 depends_on:
45 - ch-server
46 app:
47 image: ${HDX_IMAGE_REPO}/${IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
48 ports:
49 - ${HYPERDX_API_PORT}:${HYPERDX_API_PORT}
50 - ${HYPERDX_APP_PORT}:${HYPERDX_APP_PORT}
51 environment:
52 FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
53 HYPERDX_API_KEY: ${HYPERDX_API_KEY}
54 HYPERDX_API_PORT: ${HYPERDX_API_PORT}
55 HYPERDX_APP_PORT: ${HYPERDX_APP_PORT}
56 HYPERDX_APP_URL: ${HYPERDX_APP_URL}
57 HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
58 MINER_API_URL: 'http://miner:5123'
59 MONGO_URI: 'mongodb://db:27017/hyperdx'
60 NEXT_PUBLIC_SERVER_URL: http://127.0.0.1:${HYPERDX_API_PORT}
61 OPAMP_PORT: ${HYPERDX_OPAMP_PORT}
62 OTEL_SERVICE_NAME: 'hdx-oss-api'
63 USAGE_STATS_ENABLED: ${USAGE_STATS_ENABLED:-true}
64 DEFAULT_CONNECTIONS:
65 '[{"name":"Local
66 ClickHouse","host":"http://ch-server:8123","username":"default","password":""}]'
67 DEFAULT_SOURCES:
68 '[{"from":{"databaseName":"default","tableName":"otel_logs"},"kind":"log","timestampValueExpression":"TimestampTime","name":"Logs","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"Body","serviceNameExpression":"ServiceName","bodyExpression":"Body","eventAttributesExpression":"LogAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,SeverityText,Body","severityTextExpression":"SeverityText","traceIdExpression":"TraceId","spanIdExpression":"SpanId","connection":"Local
69 ClickHouse","traceSourceId":"Traces","sessionSourceId":"Sessions","metricSourceId":"Metrics"},{"from":{"databaseName":"default","tableName":"otel_traces"},"kind":"trace","timestampValueExpression":"Timestamp","name":"Traces","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"SpanName","serviceNameExpression":"ServiceName","bodyExpression":"SpanName","eventAttributesExpression":"SpanAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,StatusCode,round(Duration/1e6),SpanName","traceIdExpression":"TraceId","spanIdExpression":"SpanId","durationExpression":"Duration","durationPrecision":9,"parentSpanIdExpression":"ParentSpanId","spanNameExpression":"SpanName","spanKindExpression":"SpanKind","statusCodeExpression":"StatusCode","statusMessageExpression":"StatusMessage","connection":"Local
70 ClickHouse","logSourceId":"Logs","sessionSourceId":"Sessions","metricSourceId":"Metrics"},{"from":{"databaseName":"default","tableName":""},"kind":"metric","timestampValueExpression":"TimeUnix","name":"Metrics","resourceAttributesExpression":"ResourceAttributes","metricTables":{"gauge":"otel_metrics_gauge","histogram":"otel_metrics_histogram","sum":"otel_metrics_sum","_id":"682586a8b1f81924e628e808","id":"682586a8b1f81924e628e808"},"connection":"Local
71 ClickHouse","logSourceId":"Logs","traceSourceId":"Traces","sessionSourceId":"Sessions"},{"from":{"databaseName":"default","tableName":"hyperdx_sessions"},"kind":"session","timestampValueExpression":"TimestampTime","name":"Sessions","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"Body","serviceNameExpression":"ServiceName","bodyExpression":"Body","eventAttributesExpression":"LogAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,SeverityText,Body","severityTextExpression":"SeverityText","traceIdExpression":"TraceId","spanIdExpression":"SpanId","connection":"Local
72 ClickHouse","logSourceId":"Logs","traceSourceId":"Traces","metricSourceId":"Metrics"}]'
73 networks:
74 - internal
75 depends_on:
76 - ch-server
77 - db
78 ch-server:
79 image: clickhouse/clickhouse-server:24-alpine
80 # WARNING: Exposing the database port will make it accessible from outside the container,
81 # potentially allowing unauthorized access. If you uncomment the ports below,
82 # ensure to secure your database (e.g., with strong authentication, proper network rules, and firewalls).
83 ports:
84 - 8123:8123 # http api
85 - 9050:9000 # native
86 # environment:
87 # default settings
88 # CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
89 volumes:
90 - ./docker/clickhouse/local/config.xml:/etc/clickhouse-server/config.xml
91 - ./docker/clickhouse/local/users.xml:/etc/clickhouse-server/users.xml
92 - ./empty.xml:/etc/clickhouse-server/users.d/default-password.xml
93 - .volumes/ch_data:/var/lib/clickhouse
94 - .volumes/ch_logs:/var/log/clickhouse-server
95 restart: on-failure
96 networks:
97 - internal
98networks:
99 internal:

注意：environment 部分我注释掉了，另外加了一行：./empty.xml:/etc/clickhouse-server/users.d/default-password.xml 作用是解决 clickhouse 连接异常的问题。

通过 /data/clickhouse/hyperdx/docker/clickhouse/local/users.xml 可以看到 clickhouse 的账户信息：

 1<?xml version="1.0"?>
 2<clickhouse>
 3 <profiles>
 4 <default>
 5 <max_memory_usage>10000000000</max_memory_usage>
 6 <use_uncompressed_cache>0</use_uncompressed_cache>
 7 <load_balancing>in_order</load_balancing>
 8 <log_queries>1</log_queries>
 9 </default>
10 </profiles>
11
12 <users>
13 <default>
14 <password_sha256_hex>2d964690ad5ac2d2f78bebadc30895bc519969ffcef4d3c9e7ff04ee1c765d96</password_sha256_hex>
15 <profile>default</profile>
16 <networks>
17 <ip>::/0</ip>
18 </networks>
19 <quota>default</quota>
20 </default>
21 <api>
22 <password>api</password>
23 <profile>default</profile>
24 <networks>
25 <ip>::/0</ip>
26 </networks>
27 <quota>default</quota>
28 </api>
29 <worker>
30 <password>worker</password>
31 <profile>default</profile>
32 <networks>
33 <ip>::/0</ip>
34 </networks>
35 <quota>default</quota>
36 </worker>
37 </users>
38
39 <quotas>
40 <default>
41 <interval>
42 <duration>3600</duration>
43 <queries>0</queries>
44 <errors>0</errors>
45 <result_rows>0</result_rows>
46 <read_rows>0</read_rows>
47 <execution_time>0</execution_time>
48 </interval>
49 </default>
50 </quotas>
51</clickhouse>

密码用 sha256sum 处理过

可以这样生成：

1echo -n '你的密码' | sha256sum

运行

点击登录跳转至首页

客户端连接

用户名：default
密码：你的密码
端口：8123

数据库初始化

初始化 sql 脚本

 1/* 1. 创建数据库（如已存在可先 DROP DATABASE IF EXISTS testdb） */
 2CREATE DATABASE IF NOT EXISTS testdb;
 3
 4/* 2. 维度表：用户 */
 5CREATE TABLE IF NOT EXISTS testdb.users (
 6 user_id UInt32,
 7 user_name String,
 8 signup_date Date
 9) ENGINE = MergeTree
10ORDER BY user_id;
11
12/* 3. 维度表：页面 */
13CREATE TABLE IF NOT EXISTS testdb.pages (
14 page_id UInt32,
15 page_url String,
16 category String
17) ENGINE = MergeTree
18ORDER BY page_id;
19
20/* 4. 事实表：页面访问日志 */
21CREATE TABLE IF NOT EXISTS testdb.pageviews (
22 event_date Date,
23 event_time DateTime,
24 user_id UInt32,
25 page_id UInt32,
26 duration UInt32 -- 停留秒数
27) ENGINE = MergeTree
28PARTITION BY toYYYYMM(event_date)
29ORDER BY (event_date, user_id, page_id);
30
31/* 5. 物化视图：每日 PV / UV 聚合 */
32CREATE MATERIALIZED VIEW IF NOT EXISTS testdb.pv_uv_daily
33ENGINE = SummingMergeTree
34PARTITION BY toYYYYMM(event_date)
35ORDER BY event_date
36AS
37SELECT
38 event_date,
39 count() AS pv,
40 uniqExact(user_id) AS uv
41FROM testdb.pageviews
42GROUP BY event_date;
43
44/* 6. 演示数据插入 ---------------------------------------- */
45
46/* 用户维度 */
47INSERT INTO testdb.users (user_id, user_name, signup_date) VALUES
48 (1, 'Alice', '2024-06-01'),
49 (2, 'Bob', '2024-07-15'),
50 (3, 'Cathy', '2024-11-30');
51
52/* 页面维度 */
53INSERT INTO testdb.pages (page_id, page_url, category) VALUES
54 (10, '/home', 'landing'),
55 (11, '/pricing', 'info'),
56 (12, '/blog', 'content');
57
58/* 页面访问日志 */
59INSERT INTO testdb.pageviews (event_date, event_time, user_id, page_id, duration) VALUES
60 ('2025-07-13', '2025-07-13 09:17:00', 1, 10, 35),
61 ('2025-07-13', '2025-07-13 09:18:07', 1, 11, 50),
62 ('2025-07-13', '2025-07-13 09:19:02', 2, 10, 15),
63 ('2025-07-14', '2025-07-14 10:03:45', 3, 12, 120),
64 ('2025-07-14', '2025-07-14 10:05:22', 1, 12, 90);
65
66/* 7. 快速验证 --------------------------------------------- */
67
68/* 查看当前数据库已创建的表 */
69SHOW TABLES FROM testdb;
70
71/* 查询物化视图结果 */
72SELECT * FROM testdb.pv_uv_daily ORDER BY event_date;
73
74/* 联表查询示例 */
75SELECT
76 u.user_name,
77 p.page_url,
78 v.event_time,
79 v.duration
80FROM testdb.pageviews AS v
81LEFT JOIN testdb.users AS u ON v.user_id = u.user_id
82LEFT JOIN testdb.pages AS p ON v.page_id = p.page_id
83ORDER BY v.event_time DESC;

RAG的2024—随需而变，从狂热到理性（下）

Mon, 25 Nov 2024 06:27:48 +0000

首先感谢您的阅读，本篇分享是RAG的市场变化，上篇主要分享了RAG技术在2024年的变化。

本文主要内容：

RAG和Fine-tune目前的市场态势

RAG在这一年的市场需求变化

这一年的AI从业者观察

1.RAG vs Fine-tune

2024这一年，RAG技术对应的市场需求变化也是挺大的。在讲变化之前，我觉得有必要分享一下为什么RAG是目前市场上不可或缺的一种大模型应用的技术实现方式，它的优点是什么？以及它和主要竞争技术之间的现状是怎么样的？

RAG最开始被大家热推，更多是因为以下三个原因：

可以避开大模型的上下文窗口长度的限制；
可以更好地管理和利用客户专有的本地资料文件；
可以更好地控制幻觉。

这三点到现在来看依然还是成立的，但上下文窗口这个优势已经慢慢淡化了，因为各大模型的上下文窗口都在暴涨，如Baichuan2的192K，doubao、GLM-4的128K，过10万tokens的上下文窗口长度已经屡见不鲜，更别说一些特长的模型版本，以及月之暗面这样用长文本占据用户心智的模型。虽然这些模型是否内置了RAG技术不好说，但是RAG解决上下文窗口长度限制的特点已经不太能站得住脚。

但是第二点管理和利用专属知识文件，以及第三点控制幻觉，现在反而是我认为RAG最大的杀手锏。

01 专属知识文件管理

因为RAG这种外挂文件的形式，我们便可以构建一个知识文件管理的系统来维护系统内的知识，包括生效和失效时间，知识的协作，以及便捷地为知识更新内容等。RAG在知识维护上，既不需要像传统NLP那样由人工先理解再抽取问答对，也不需要像微调（fine-tune）那样需要非常专业的技术能力，以及微调之后的繁琐对齐（alignment）优化。所以如果客户的知识内容更新比较频繁（假设每天需要追加、替换大量实时资讯内容），特别是金融证券、企业情报等场景，RAG知识更新便捷的特性真的非常合适。

02 RAG的幻觉控制

RAG的幻觉控制是一个有争议的话题，我之前写过类似观点，也有同学斩钉截铁地认为RAG和幻觉控制八竿子打不着，但我现在依然坚持RAG可以有效控制幻觉这个观点。

首先我们可以来看看LLM幻觉产生的主要原因：

对于用户的提问输入，LLM内部完全没有相应的知识来做应对。比如你问大模型，上周三我在思考一件事，但是现在想不起来，你帮我想想是什么。例子虽然夸张，但显而易见，LLM也不知道，但是它会一本正经给你一些建议，当然肯定不是你想要的；
当我们给LLM原始问题，以及多个模棱两可或互相影响的参考材料，那么LLM给出的最终答案也会出错。

好，那么针对以上问题，是否我们解决好对原始问题的**“理解-检索-召回”**，送到LLM的context足够清晰（指的是没有歧义内容、检索相关度高），结果就会非常准确？根据我们的实践结果，答案是明确的：

今年9月份我们对一些项目进行了槽位填充（消除模糊问答）和元数据辅助之后，问答准确率可达到98%以上。比直接把大文本扔进同一个LLM测试的问答准确率几乎高出14个百分点。

有同学会说，LLM幻觉的深层原因是temperature或者说概率引起的。就我纯个人观点来看，现当下的LLM参数足够大、知识量足够多，temperature引起的偏差对于最终结果的正确性影响已经微乎其微了。

03 市场表现

你应该看出来了，在RAG和微调之间，我明显站队了，而且从一年前就开始站队了，我们创业的技术方向也是如此。从今天来看，我觉得RAG在2024年的表现确实要强于微调。

图：Menlo Ventures在2024年11月20日发布的市场调研报告。RAG以51%的市场份额在企业市场份额中占据绝对优势，Fine-tune和Prompting工程均下降两倍多。Agent今年属于纯增长，目前情况还不错，但在企业应用领域，多Agents的编排依然存在理解能力不足和生成幻觉等问题有待提高。

来源：https://menlovc.com/2024-the-state-of-generative-ai-in-the-enterprise/

如果去预测明年的企业级市场趋势，我觉得应用（Application）可能会是最大的关键词，甚至会超过Agent的热度。其实今年下半年已经能明显的看出来，越来越多传统大企业开始将大模型技术引入到业务中，而且他们的特点是“要求高”、“需求刚”、“付费爽”。而一旦大家开始在大模型的应用侧竞赛，RAG在整个业务流程中“白盒流程多”、“易控”等特点愈发会受到企业客户和开发者的热捧，优势进一步拉大。

2.市场变化之2024

关于企业AI应用市场在2024年的变化，我之前已经有写过文章《聊个五分钟的企业AI应用需求发展趋势》，这里就简单再总结一下。

上半年：AI无所不能，大而全

2024年的上半年，AI市场充斥着激情，那种热情似乎走在街上都会扑面而来，个人感觉最主要的推动者是自媒体和模型厂商。模型厂商的出发点很容易理解，快速打开市场嘛，但考虑到他们是要最终交付的，所以相对还是比较理性。但自媒体就一样了，整个上半年看过太多的文章，大家也都是把最好的一面呈现给了大众，所以很多人会觉得我才几个月没关注，AI已经发展到我不认识的地步了，AI已经无所不能了。所以，在2024年上半年，我们接触到的企业需求中，占主流的是那种大而全的需求，要用AI替代他们业务的全流程或基本流程，气味中充满了使用者的野望。

但实际情况并不理想，AI或者大模型还真没到这个程度，而且最关键的是范式转换也还需时间。什么是范式转换？最简单的例子就是以前人们用笨重的蒸汽机推动主轴承转动，带动整车间的机器工作。但是换了电动机之后呢，工作方式变了，动力可是变得非常分散，比如你拿在手上吹头发的吹风机。带着微型电动机的吹风机和传统的蒸汽机在工作范式上就完全不同，采用AI大模型之后，企业的业务流程也存在范式改造的过程，并非一朝一夕可以完成的。

所以，上半年我遇到的、参与的或者听说的那些大而全的AI项目，一半是在可行性推演中没有被验证，一半是交付之后效果很不理想，成功者寥寥。

下半年：回归理性，小而难

在今年7月份开始，陆续有一些传统大企业找上门来，包括非常知名的企业，以及世界500强和多家中国500强。如果从时间上来说，他们属于AI投入相对较晚的了，但他们的优势是需求非常明确，要求也极高。比如有些企业仅仅就是解决一个咨询服务的需求，在产品范围上就是一个AI问答，但要求准确率接近100%，就像我们CTO在《AIGC时代的淘金者，TorchV这一年的心路历程》说到社保咨询一样。

小而难的好处很明显，我能看到的是下面几点：

对企业现有业务流程改造相对较小，内部推动的阻力相对较小，企业客户配合度高；
切口小，需求明确，建设成果的考核清晰可量化；
使用功能较小但可用性较高的AI产品，可以让企业内部员工快速接受AI，做进一步业务流程改造的前期预热；
乐于承接大而全需求的合作厂商多半是外包性质的（这个观点有点伤人，但确实是我看到的现状），而专业的、交付成功率更高的厂商往往更喜欢需求清晰且有难度的任务。

关于2025年的预测

我在上文中已经有提到，2025年会有更多企业需求方采用AI技术，但企业永远不会为你的技术买单，他们只会为他们自己的使用价值买单。比如可以帮助他们提升销售额、业务流转效率更高，或者和竞争对手的竞争中获得优势，还有就是降低成本等等。所以，大模型应用端多端不够，还需要生长出藤蔓围绕着企业流程开花结果，这个任务最终会落在应用（Application）——内化了企业流程、借助了大模型能力的、带有可交互界面的程序。我自己预测2025年会成为大模型应用或AI应用之争。

另外还有一个趋势也很明显，就是知识管理和协作。我们都说这波AI浪潮把原来“没用”的非结构化数据给激活了，嗯，所以我们马上会看到那些原来堆在角落里面的“冷”文件和知识（类似wiki）会被大量启用，“热”文件和知识会爆炸性增长，知识的协作和管理会成为新的问题——就像你有再多的先进坦克和战车，却因为无序的交通都堵在阿登森林了。基于大模型的知识管理和协作，会在12月专门写一篇文章好好分享一下我自己的见解，希望能找到共鸣的客户以及开发者。

3.AI从业者观察

因为我看到的不代表真相，所以这一章节会很短，仅仅分享两个发现。

01 AI技术的下坡

图：技术采用生命周期。现阶段的AI大模型市场似乎正处于过高期望之后的下坡过程中。

有两个感受（非证据）可以说明这一点：

关于AI大模型的自媒体数量在减少，从搜索引擎趋势，加上我和几个业内朋友的blog、公众号以及X的阅读量下降趋势也可以佐证这一点，下半年虽然市场理性回归，但整体热度是在下降的。OpenAI不再持续放大招可能也是重要原因之一；
我前期接触了很多因为AI热潮而在企业内部抽调精干力量组成的AI小组、AI研究组和AI创新组等团队的成员，但下半年有不少类似团队已经解散，人员回归到原有岗位。

还有一点就是上半年加我微信好友的很多独立开发者或在职的个人，多半也已经在寻觅了半年机会之后放弃了继续探索，这一点在和他们交流，以及他们朋友圈的内容变化中可以明显感知。

但是这并不是坏事，上图已经告诉我们，这是必然规律。

02 价值开始显现

第二个观察就是目前还奔跑在AI大模型应用赛道的公司，很多已经开始创造出客户价值，有了自己的优势。

包括在海外风生水起的Dify，在内容提取端的合合，以及肯定会成为国内AI巨无霸的火山引擎。当然我们还看到了一些深耕垂直行业的优秀团队，特别是在法律、医药、教育等行业。我们也在今年6月份开始做了产品转身，现在已经不再烦恼人家问我们“你们和dify/fastgpt/ragflow有什么区别？”，因为赛道已经开始慢慢不一样了，而且这个不一样依然是产品层面的，和服务什么行业无关。关于这一点，也还是在12月的那篇文章再来分享吧。

三、总结

好了，这篇文章就写到这里了，上篇从个人观点分享了RAG技术这一年的变化，下篇分析了RAG的市场发展情况。最后介绍一下我们自己的产品品牌TorchV，我们通过RAG进行扩展延伸，已经服务了不少大型客户。如果您想在企业中引入AI大模型能力来提升业务，欢迎找我们沟通，以下是我的微信二维码。

ps：我们最近在招聘实习生，如果您对AI发展非常感兴趣，是在杭州的在校大学生，且有一定的vue/Java/Python编程能力，请联系我。

RAG的2024—随需而变，从狂热到理性（上）

Mon, 25 Nov 2024 06:27:48 +0000

首先感谢那些依然关注着“土猛的员外”的朋友们，对你们，肃然起敬！

转眼到了2024年尾，和小伙伴一起创立TorchV也接近一年。虽然这一年做了很多事情，但从技术层面上来说，RAG肯定是不得不提的，所以今天分享一下作为大模型应用创业者所感知的这一年，RAG技术和市场环境的变化。

首先声明，本文更多来自于本人主观感受，且内容更多是回顾性的结论，不建议作为其他文章的引用材料。

主要内容包括：

RAG技术变化

主要架构变化

技术细节变化

市场需求变化

上半年：AI无所不能，大而全；

下半年：回归理性，小而难；

明年预测：应用才是王道；

从业者变化。

其中技术部分放在上篇，市场需求变化放在下篇。

一、RAG技术变化

RAG（检索增强生成）其实是由两部分组成的，分别是检索和大模型生成。当然，既然有检索就必然会先有索引，包括chunking、embedding等动作都是为了建立更好的索引。因为我们之前从零开始创建并运营了一个千万级用户的智能问答类产品，所以在2021年左右其实就已经采用Java技术栈在使用RAG里面“RA”的大部分技术了。在2023年年中，RAG这个词突然火了起来，于是我们就立马就扑进去了，而且相信RAG在企业应用领域比纯粹使用大模型会更具实用性，至少在三年之内是这样的（随着最近传闻Scaling Law遇到瓶颈，好像这个时间还有可能被推后）。短短几个月，RAG开始的火爆程度甚至有超过LLM的趋势，在2024年1月我甚至还参加了“共识粉碎机”的EP15讨论会，主要话题就是**“2024年是否会成为RAG元年？”**。

1.主要架构变化

虽然RAG的火热，各种架构思想就被大师们总结出来，最出名的莫过于下面这张图了：

RAG三种技术架构

图1:RAG三种架构模式，来源于论文Retrieval-Augmented Generation for Large Language Models: A Survey。

站在现在（2024年11月）再看，其实Advanced RAG应该还是最主流的架构。因为它的效果明显比Naive RAG要好，但比Modular RAG更容易实现。在实际应用中，我们还需要为客户考虑经济成本和维护成本，很多时候基于客户需求，在Advanced RAG上做一些对症下药，远比全家桶更具适应性。

2.技术细节变化

相较于架构变化，技术细节的变化更加“风起云涌”，这一点从各自媒体的文章主题变化和从业者之间的交流内容中就能明显感知到。在RAG这个大框架之下，我们看到了每隔一段时间就会有一些技术细节被热炒，比如：

知识提取
索引组织
检索方法

01 知识提取

在2024年之前，我们看到的RAG面对的原始知识更多是非常标准的论文，一般是文字版PDF或者HTML，所以那时候内容提取还不是一个大问题。但是在2024年，随着各行各业都开始使用RAG之后，五花八门的文件类型解析变成了从业者们头痛的事情，于是，我们发现有好一波人开始专注于知识提取。

于是我们看到在2024年，出现了很多专门做知识提取的公司，比如已经在科创板上市合合信息（其实已经是老牌企业），在文件解析方面就非常出色，还有新创的SoMark等，当然大厂在这一块肯定也都涉足，特别是OCR解析，比如百度开源的PaddleOCR，其实还挺良心的。

我们也是如此，看到现成的python组件在面对多样的知识文件类型时渐感无力，于是就开始在知识提取方面花时间。从多类型文件的解析，包括一些老文件格式（.doc、.xls、.ppt等）的解析，再到比较难的PDF表格解析，需要去处理非常复杂的合并/拆分单元格，并且也有了具备原创知识产权的提取工具组件。

但是我一直在想，是否可以把整个工作流再前置，如果我们提供知识生产工具，用户可以在我们的知识管理和生产工具上进行知识生产和协作，那么知识提取是不是会更流畅？这个问题可以单独写一篇文章，就放在这个篇文章的上下篇结束之后吧。

02 索引组织

在RAG里面，索引组织可能是相对比较有技巧性的部分了。

了解RAG的人都听过chunking，不严谨地说，就是把文件切成若干片段，为的是可以在LLM的窗口大小之内进行作业。常见的chunking方式有按固定token数量的，有按Page的，也有通过NLTK等来进行切分的。但我始终觉得使用哪种chunking方法并不是重点，如果您使用的LLM的上下文窗口较大，对于一些4、5页的文件，还切它干嘛呢，直接扔进去就完事了。但在chunking过程中，其实有两个隐含的技巧是可以快速提升准确率的：指代消解和附加元数据。

指代消解

我们在实操中常见的是两种，一种是切割的时候，上一页有详细信息，而下一页中只有“这种方法”来指代。这时候最简单的方法就是做chunk叠加；还有一种就是类似合同，甲方乙方的具体名字只在最开头的地方出现，剩下全文都用“甲方”、“乙方”指代，这种情况因为被指代的名称是比较好获取的，可以直接加在chunk中，如下所示（伪代码），chunk_meta里面可以设置甲方乙方的全称：

<chunk> <chunk_meta> ... </chunk_meta> <chunk_content> ... </chunk_content> </chunk>

附加元数据

其实元数据的索引存储结构和上面的指代消解示例中差不多，不同的是，我们需要关心的是：

元数据从哪里来？
在检索的过程中什么情况下激活元数据过滤？

元数据的来源只可能是人工标注或者应用侧（包括文件处理时）生成的，这里我们肯定先不去考虑人工标注了。从应用侧的设计来看，其实是可以拿到很多元数据的。比如我们上传文件、撰写知识的时候，自然可以拿到时间、文件名称（正常命名都会含有实体），也可以在交互设计中要求作者进行分类选择，简介编写等，无一不是增加元数据的手段。

但我们在索引中增加了元数据内容之后，也不是强行要激活元数据过滤的。我们在实操中是会设置自定义的系统槽位（system_slot），如果用户提问的文本中，也包含比较多的意图和实体信息，且与系统槽位存在匹配，才会激活。会先使用BM25进行元数据过滤，再进行dense检索。更具语义信息的dense索引有时候因为维度限制会丢失一些信息，或者说dense检索对于元数据过滤并不那么精准。这种设计一方面可以减少检索的时间，另一方面就是可以提高带有时间和实体（如城市、公司、部门等）意图的提问的准确率。说起来这好像是一种“退步”，因为当LLM（或GPT）所向披靡的时候，我们也是一度有点看不上之前的技术的，但是在企业应用实践中，客户问题的解决率才是一切的根本。所以，在TorchV AI中，我们让NLU和Slot（槽位填充）回归了。

使用槽位填充的对话

是否使用Graph

对了，还有一个大家争论比较多的索引组织方式就是Graph或者叫图数据，将node（实体）和relation（关系）通过图论组织起来。我们团队从2015年开始一直有在使用neo4j开发一些有趣的应用，在寻找人类直观上不太容易识别的点与点关联的方面确实非常出色。但是这个技术非常大的问题就是索引建立，从关系数据库把结构化数据迁移到Graph数据库中还算容易，但是面对成千上万的非结构化数据的时候，说实话目前也就是只能让GPT4以上的LLM来帮忙了。和重度使用过图知识库的朋友聊的过程中，他们的一致感受是：花费太高昂，但是场景太薄弱，依然还存在手工校对的工作。换句话说，如果花了10万的费用，但在实际使用中却没这么多使用场景，得不偿失。

当然，如果您手头的工作非Graph不能解决，那就大胆去All-in吧。我们目前的系统并没有使用图数据库。

03 检索方法

有句话（我说的）不一定说的对，在某种意义上，知识提取决定了专有知识的完整性，索引组织决定了回答准确率，而检索方法则在减少幻觉上有重要意义。

如果我们可以准确检索召回，把非常明确的内容加上指令prompt，给到LLM处理，那么LLM给出的结果几乎不太会一本正经胡说八道。只有检索召回的内容和用户原问题不相关，或者召回内容存在多个不置可否的知识内容时，LLM才会按心情（概率和 temperature）选择错误知识或者使用预训练时学习的知识进行回答。所以，检索做得好，可以将整个RAG幻觉尽可能多的变为白盒。

Hybird

但是说到检索，我相信现在大部分的RAG系统都已经用上了Hybird检索了吧，一般来说也就是BM25+语义相似检索的混合检索。

BM25有自己的固有用武之地，就像前面说的元数据过滤，还有就是一些在类似产品型号和专业术语的检索上，其精确度和稳定性是远高于语义相似检索的。

语义相似检索有很多方法，因为我们主要用的还是Elasticsearch（也有Milvus），所以其实真正的语义相似检索就是ANN，说的更具体就是以HNSW为主的相似度算法。这个HNSW（最小可导航世界）的逻辑解释起来有点麻烦，但是我可以打一个比方：

比如你需要从一个城市的南部坐公交去北部，我们要选择最短的坐车路线（含换乘），那么有两种方式选择：

knn：将所有可能的公交路线（含换乘）做一个整理，假设有28900条路线，然后按花费时间进行排序，选择Top1或者Top n。抛开语义理解错误的问题，这种方法是非常精确的，但是耗时巨大，也可以认为是一种暴力检索；

ann：还有一种就是相似最近邻，我们这里说到更多的是hnsw。为了让非技术专业的朋友可以听懂，不严谨地说，看着地图，从28900条路线中，选择出发地和目的地两点连线附近的50或100条公交路线。这种方法的效率极高，可能耗时只需要knn的万分之一，但它的问题在于无法确定这50或100条里面哪几条才是最好的。于是，如果你采用ann却不用rerank的话，就会比较拉垮了。

RRF Fusion

RAG-Fusion主要是使用多个不同类型的检索方式进行检索，并按RRF（倒数排序融合）公式进行综合排名的一种检索方式。

多种检索方式包括：

Sparse（稀疏）检索，比如BM25；
Dense（稠密）检索，比如语义相似度检索；
还有就是使用不同配比的混合检索（在TorchV AI中，我们采用alpha值来做BM25和ANN的结果权重配比）。

然后使用RRF公式

RRF(d) = Σ(r ∈ R) 1 / (k + r(d))

具体公式就不解释了，有兴趣的朋友自己查资料吧。

来进行再排序，得出一个综合结果。其好处是使用不同的检索器，可以在各类不同问题场景下得到一个“思考”更周密的答案。我们在的系统里面有一个turbo开关，打开就会进行增强检索，其中也包括了该方法，且在召回率方面是有一定效果的。

Rerank

其实我应该不用再讲reank了，如果您看过上面hnsw算法的话，就能知道rerank的作用了。TorchV AI在使用rerank的时候也加入了自己的一些优化算法，比如归一化处理和密度函数（舍弃相关性较低的返回结果）。在使用rerank前后，准确率相差确实很大，但你要平心而论，元数据过滤对准确率的提升可能会更明显。因为rerank相对比较被动（根据前序召回的结果，有时候是矮子里拔将军），而元数据过滤则是直接在检索召回环节产生影响，相对更加主动（自己对召回哪些结果起到重要作用）。嗯，这是我自己的理解，不一定对。

3.技术部分小结

OK，RAG技术变化我想先做个小结。

关于RAG的大流程已经有太多文章了，我自己也写了不少，所以本文我更希望是从点而不是面的角度来讲一些技术实践上发现的变化。其实从RAG本身的各环节技术来说，没有出现新的现象级组件，2024这一年，看到更多的，是碰撞实际需求、探索最佳实践、内化到系统能力中的一个过程。

市场变化的部分，下周差不多时间发布，敬请期待

如果您对TorchV AI的产品有兴趣，也可以直接联系我：

Redis6.0 以后为什么使用了多线程？

Mon, 18 Nov 2024 02:04:32 +0000

Redis 所谓的单线程并不是所有工作都是只有一个线程在执行，而是指 Redis 的网络 IO 和键值对读写是由一个线程来完成的，Redis 在处理客户端的请求时包括获取 (socket 读）、解析、执行、内容返回 (socket 写）等都由一个顺序串行的主线程处理。

这就是所谓的“单线程”。这也是 Redis 对外提供键值存储服务的主要流程。由于 Redis 在处理命令的时候是单线程作业的，所以会有一个 Socket 队列，每一个到达的服务端命令来了之后都不会马上被执行，而是进入队列，然后被线程的事件分发器逐个执行。如下图：

至于 Redis 的其他功能，比如持久化、异步删除、集群数据同步等等，其实是由额外的线程执行的。可以这么说，Redis 工作线程是单线程的。但是在 4.0 之后，对于整个 Redis 服务来说，还是多线程运作的。

6.0 之前为什么要使用单线程

在使用 Redis 时，Redis 主要受限是在内存和网络上，CPU 几乎没有性能瓶颈的问题。
以 Linux 系统为例子，在 Linux 系统上 Redis 通过 pipelining 可以处理 100w 个请求每秒，而应用程序的计算复杂度主要是 O(N) 或 O(log(N)) ，不会消耗太多 CPU。
使用了单线程后，提高了可维护性。多线程模型在某些方面表现优异，却增加了程序执行顺序的不确定性，并且带来了并发读写的一系列问题，增加了系统复杂度。同时因为线程切换、加解锁，甚至死锁，造成一定的性能损耗。
Redis 通过 AE 事件模型以及 IO 多路复用等技术，拥有超高的处理性能，因此没有使用多线程的必要

6.0 之后的多线程主要解决什么问题

近年来底层网络硬件性能越来越好，Redis 的性能瓶颈逐渐体现在网络 I/O 的读写上，单个线程处理网络 I/O 读写的速度跟不上底层网络硬件执行的速度。

Redis 在处理网络数据时，调用 epoll 的过程是阻塞的，这个过程会阻塞线程。如果并发量很高，达到万级别的 QPS，就会形成瓶颈，影响整体吞吐能力

既然读写网络的 read/write 系统调用占用了 Redis 执行期间大部分 CPU 时间，那么要想真正做到提速，必须改善网络 IO 性能。我们可以从这两个方面来优化：

提高网络 IO 性能，典型实现方式比如使用 DPDK 来替代内核网络栈的方式
使用多线程，这样可以充分利用多核 CPU，同类实现案例比如 Memcached。

协议栈优化的这种方式跟 Redis 关系不大，所以最便捷高效的方式就是支持多线程。总结起来，redis 支持多线程就是以下两个原因：

可以充分利用服务器 CPU 的多核资源，而主线程明显只能利用一个
多线程任务可以分摊 Redis 同步 IO 读写负荷，降低耗时

6.0 版本优化之后，主线程和多线程网络 IO 的执行流程如下：

具体步骤如下：

主线程建立连接，并接受数据，并将获取的 socket 数据放入等待队列；
通过轮询的方式将 socket 读取出来并分配给 IO 线程；
之后主线程保持阻塞，一直等到 IO 线程完成 socket 读取和解析；
I/O 线程读取和解析完成之后，返回给主线程，主线程开始执行 Redis 命令；
执行完 Redis 命令后，主线程阻塞，直到 IO 线程完成结果回写到 socket 的工作；
主线程清空已完成的队列，等待客户端新的请求。

本质上是将主线程 IO 读写的这个操作独立出来，单独交给一个 I/O 线程组处理。这样多个 socket 读写可以并行执行，整体效率也就提高了。同时注意 Redis 命令还是主线程串行执行。

利用多核来分担 I/O 读写负荷。在事件处理线程每次获取到可读事件时，会将所有就绪的读事件分配给 I/O 线程，并进行等待，在所有 I/O 线程完成读操作后，事件处理线程开始执行任务处理，在处理结束后，同样将写事件分配给 I/O 线程，等待所有 I/O 线程完成写操作。

 1int handleClientsWithPendingReadsUsingThreads(void) {
 2 ...
 3 /* Distribute the clients across N different lists. */
 4 listIter li;
 5 listNode *ln;
 6 listRewind(server.clients_pending_read,&li);
 7 int item_id = 0;
 8 // 将等待处理的客户端分配给 I/O 线程
 9 while((ln = listNext(&li))) {
10 client *c = listNodeValue(ln);
11 int target_id = item_id % server.io_threads_num;
12 listAddNodeTail(io_threads_list[target_id],c);
13 item_id++;
14 }
15 ...
16 /* Wait for all the other threads to end their work. */
17 // 轮训等待所有 I/O 线程处理完
18 while(1) {
19 unsigned long pending = 0;
20 for (int j = 1; j < server.io_threads_num; j++)
21 pending += io_threads_pending[j];
22 if (pending == 0) break;
23 }
24 ...
25 return processed;
26}

本质上是利用多核的多线程让多个 IO 的读写加速。

局限性

6.0 版本的多线程并非彻底的多线程，I/O 线程只能同时执行读或者同时执行写操作，期间事件处理线程一直处于等待状态，并非流水线模型，有很多轮训等待开销。

Milvus实战：如何用一个数据库提升你的AI项目性能

Fri, 11 Oct 2024 08:22:08 +0000

回顾

在上一文中我们使用 LlamaIndex 整合智谱 AI 的 GLM-4 和 Embedding-3 模型一起构建 RAG 应用。

在上篇文章的最后，我们发现因为 Embedding-3 模型是同步调用的，所以从测试效果看比较慢。每一次运行都产生了大量的 http 同步请求。文末我说解决的办法可以在本地部署一个开源的 embedding 模型，这样就不会产生远程的 http 调用了，而且也比较省钱。

这是个办法，但实际上还有其他的好办法。

我们可以将文档通过 embedding 模型产生的向量存储起来，这样相同的文档，只有在第一次 embedding 时会慢一些，再次检索时，可以快速地将已经保存好的向量查询出来使用。

本地文件存储

利用 LlamaIndex 的 API ，我们可以非常方便地把向量存储到本地文件，以下是一个例子，我把向量存储到项目的 index目录下：

 1def load_or_create_index():
 2
 3 # 检查是否存在有效的持久化索引
 4 if (
 5 os.path.exists("index")
 6 and os.path.isdir("index")
 7 and any(file.endswith(".json") for file in os.listdir("index"))
 8 ):
 9 print("正在加载现有索引。..")
10 storage_context = StorageContext.from_defaults(persist_dir="index")
11 index = load_index_from_storage(storage_context)
12 else:
13 print("未找到有效的现有索引，正在创建新索引。..")
14 # 使用预定义的 DATA_DIR 常量
15 documents = SimpleDirectoryReader("./data").load_data()
16 # 创建新索引，显示 embedding 进度
17 index = VectorStoreIndex.from_documents(documents, show_progress=True)
18 # 持久化索引
19 index.storage_context.persist(persist_dir="index")
20 print("索引已创建并保存到本地。")
21
22 return index

看起来代码多，实际上重要的就是这两行：

1storage_context = StorageContext.from_defaults(persist_dir="index")
2index = load_index_from_storage(storage_context)

也很容易理解，见文知意。

索引创建后，index 会自动创建一些文件来保存向量信息：

向量数据库

一般情况下，比如小型项目，将向量数据保存在系统文件中就已经够用了。但是，在中大型项目中，由于数据规模较大，使用人数较多，为了方便管理和扩展，我们会使用专业的向量数据库来存储和管理向量数据。

你可以借助下图了解下向量数据库在 AIGC 应用架构中的位置和作用

向量数据库选型

“

RAG 系统的成功在很大程度上取决于其高效地获取和处理海量信息的能力。向量数据库又在其中发挥了不可替代的作用，并构成了 RAG 系统的核心

不看不知道，作为一个数据库软件，目前向量数据库领域是真卷啊，打眼一看至少有几十个。知名的也得有 10 几个。

说实话，最开始还真有些茫然，有点儿挑花眼了，我们这里列举几个知名的向量数据库：

Milvus 是一个 2019 年开源的纯向量数据库，号称全球最先进的开源向量数据库。它是 LF AI & Data Foundation（简称 LFAI，它相当于 CNCF 在云原生界的地位）赞助的毕业项目
Chroma 是一个相对较新的向量数据库，目前它的设计确实是以单节点模式为主，主要用于中小型应用或开发测试环境。然而，对于需要更高可用性和横向扩展能力的生产环境，Chroma 当前的版本可能还不完全满足需求。Chroma 内置了 SQLite 作为其底层存储引擎
Weaviate ：是一个云原生的、开源的向量数据库。专为大规模的向量数据存储和检索设计。它结合了向量搜索和图数据库的优势，适用于机器学习、推荐系统、图像识别和自然语言处理等场景。
Faiss ：由 Facebook AI Research 开发的 Faiss 是一个开源库，用于快速、密集向量相似性搜索和分组
Qdrant 是一个开源的向量数据库，专为高效的大规模向量数据存储和检索设计。它适用于机器学习、推荐系统、图像识别和自然语言处理等场景，提供了高性能和易用性的结合。
PGVector 是一个基于 PostgreSQL 的扩展插件，旨在提供强大的向量存储和查询功能，PGVector 可以无缝集成到现有的 PostgreSQL 数据库中，用户无需迁移现有的数据库即可开始使用向量搜索功能。因为是 PostgreSQL 插件，借助 PostgreSQL 的长期开发和优化，PGVector 继承了其可靠性和稳健性，同时在向量化处理方面进行了增强。

整体上看在向量数据库领域有这么几类玩家：

专做向量数据库的，大部分是开源的，如 Chroma、Weaviate 等
做关系型数据库的扩展或插件，如 PGVector
做 NoSQL 数据库的功能扩展或兼容，如 Elasticsearch、 Redis、 ClickHouse 等

太多了，真是太多了，最开始我做选型的时候真是有点儿挑花眼了。最后，一点点缩小范围，最终进入决赛圈的是：

Qdrant
Weaviate
Milvus

你可以通过 https://zilliz.com.cn/comparison 来了解各向量数据库之间的对比情况

最终我选择了 Milvus 原因是：

它确实很知名，看了那么多评测，各方面性能都很能打
我个人觉得比较重要的是它还有数据库管理客户端 attu

向量数据库不像我之前使用过的关系型数据库，一般是没有像 Navicat 、DataGrip 这样的数据库管理客户端的。一般只有 CRUD 接口或 CLI 客户端。这对于初学者了解和学习向量数据库不太友好，所以我还是特别希望有这样一个有 GUI 图形界面、看得见摸得着的客户端的，而 Milvus 正好是有的。就是 attu （可以通过 https://github.com/zilliztech/attu 下载）

如果你也和我一样在 Qdrant、Weaviate、Milvus 之间纠结的话，可以参考网上一位大哥对它们的评价：“总结起来就是，Qdrant 开销特别小，Weaviate 支持向量搜索、对象存储和倒排索引的组合，Milvus 性能最强、花活最多。”

Chroma

LlamaIndex 官方的例子使用的是 Chroma 作为向量数据库进行向量存储。

默认情况下，Chroma 会将向量数据存储在本地文件系统中。我们就以 Chroma 为例写个例子。

Chroma 不需要安装外部软件，安装导入相关的库就可了

1import chromadb
2from llama_index.vector_stores.chroma import ChromaVectorStore

在导入了 Chroma 相关的库后，我们将 load_or_create_index() 方法调整一下：

 1def load_or_create_index():
 2 
 3 # 初始化客户端，设置数据保存路径
 4 db = chromadb.PersistentClient(path="./chroma_db")
 5 # 创建或获取集合
 6 chroma_collection = db.get_or_create_collection("quickstart")
 7 # 将 chroma 指定为上下文的 vector_store
 8 vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
 9 storage_context = StorageContext.from_defaults(vector_store=vector_store)
10
11 # 检查集合是否为空
12 if chroma_collection.count() == 0:
13 # 如果集合为空，加载文档并创建新的索引
14 documents = SimpleDirectoryReader("./data").load_data()
15 index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
16 print("已创建新的索引")
17 else:
18 # 如果集合不为空，直接从 vector_store 加载索引
19 index = VectorStoreIndex.from_vector_store(vector_store, storage_context=storage_context)
20 print("已加载现有索引")
21
22 return index

可以看到也很简单。程序运行后，chroma_db 文件夹下会自动创建以下文件：

前文中我们提到过 chroma 内置了 SQLite ，这里就体现出来了。

Milvus

在使用 Milvus 前我们需要先安装它。它有多种安装方式，我本地通过 Docker-Compose 安装

 1version: '3.5'
 2
 3services:
 4 etcd:
 5 container_name: milvus-etcd
 6 image: quay.io/coreos/etcd:v3.5.14
 7 environment:
 8 - ETCD_AUTO_COMPACTION_MODE=revision
 9 - ETCD_AUTO_COMPACTION_RETENTION=1000
10 - ETCD_QUOTA_BACKEND_BYTES=4294967296
11 - ETCD_SNAPSHOT_COUNT=50000
12 volumes:
13 - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
14 command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
15 healthcheck:
16 test: ["CMD", "etcdctl", "endpoint", "health"]
17 interval: 30s
18 timeout: 20s
19 retries: 3
20
21 minio:
22 container_name: milvus-minio
23 image: minio/minio:RELEASE.2023-03-20T20-16-18Z
24 environment:
25 MINIO_ACCESS_KEY: minioadmin
26 MINIO_SECRET_KEY: minioadmin
27 ports:
28 - "9001:9001"
29 - "9000:9000"
30 volumes:
31 - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
32 command: minio server /minio_data --console-address ":9001"
33 healthcheck:
34 test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
35 interval: 30s
36 timeout: 20s
37 retries: 3
38
39 standalone:
40 container_name: milvus-standalone
41 image: milvusdb/milvus:v2.3.0
42 command: ["milvus", "run", "standalone"]
43 security_opt:
44 - seccomp:unconfined
45 environment:
46 MINIO_REGION: us-east-1
47 ETCD_ENDPOINTS: etcd:2379
48 MINIO_ADDRESS: minio:9000
49 volumes:
50 - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
51 healthcheck:
52 test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
53 interval: 30s
54 start_period: 90s
55 timeout: 20s
56 retries: 3
57 ports:
58 - "19530:19530"
59 - "9091:9091"
60 depends_on:
61 - "etcd"
62 - "minio"
63
64networks:
65 default:
66 name: milvus

安装好以后，可以看到它内部有三个容器：

接着我们安装 attu，它的安装比较简单，下载相关平台的安装文件安装即可

attu 安装完成后打开进行 Milvus 的连接：

默认地址是 127.0.0.1:19530

接着，我们来到程序这里，进行连接和使用，同样，要先导入库

1from llama_index.vector_stores.milvus import MilvusVectorStore

然后我们调整一下之前的方法，改写一个新的方法来连接 Miluvs:

 1def get_or_create_index(is_create: bool = False):
 2 """
 3 获取或创建索引
 4 overwrite 设置为 False 意味着如果同名的集合已存在，将不会覆盖它。
 5 dim 是向量维度，必须与 embedding 模型的维度一致。
 6 """
 7 vector_store = MilvusVectorStore(
 8 uri="http://localhost:19530",
 9 dim=256,
10 overwrite=False,
11 collection_name="llamaindex_collection",
12 )
13
14 if is_create:
15 storage_context = StorageContext.from_defaults(vector_store=vector_store)
16 documents = SimpleDirectoryReader("./data").load_data()
17 index = VectorStoreIndex.from_documents(
18 documents, storage_context=storage_context
19 )
20 print("已成功创建并存储新的索引。")
21 else:
22 index = VectorStoreIndex.from_vector_store(vector_store)
23
24 return index

我相信如果你阅读了前文，知道这段代码的重要点在哪里。

当 RAG 应用程序正常运行后，向量数据就被存储到了 Milvus 数据库中：

有了 GUI 界面，就比较直观地能感受到向量数据是个什么样子了。

有关在 attu 中进行向量数据的查询等操作可以参数相关文档，本文就不多说了。

使用向量数据库存储以后，我们再次运行查询，速度就很快了，因为第一次运行的时候就已经把文档 embedding 后的向量存储起来了，只需要从 Milvus 中加载查询就可以了，不用再走 http 远程调用。

总结

在本文中，我们深入探讨了如何通过 LlamaIndex 整合智谱 AI 的 GLM-4 和 Embedding-3 模型来构建 RAG 应用，并针对 Embedding-3 模型同步调用导致的性能瓶颈问题，提出了有效的解决方案。我们发现，将文档的向量存储起来，可以显著提高检索速度，避免了重复的 HTTP 同步请求，从而节省了成本和时间。

通过本地文件存储和向量数据库的选型，我们对比了多种向量数据库的特点和性能，最终选择了 Milvus 作为我们的向量数据库。Milvus 以其卓越的性能和易用性脱颖而出，特别是其数据库管理客户端 attu，为初学者提供了友好的图形界面，使得向量数据库的管理和操作变得更加直观和便捷。

在实际应用中，我们通过 Docker-Compose 安装了 Milvus，并利用 attu 进行了连接和操作。通过将向量数据存储到 Milvus 数据库中，我们显著提高了查询速度，因为文档的向量在第一次运行时就已经被存储起来，后续的查询可以直接从 Milvus 中加载，无需再次进行远程 HTTP 调用。

此外，我们还探讨了使用 Chroma 作为向量数据库的方案，它内置了 SQLite，简化了安装和使用过程。通过 LlamaIndex 的 API，我们可以轻松地将向量存储到本地文件或 Chroma 数据库中，进一步增强了 RAG 应用的性能和可扩展性。

总的来说，通过本文的探讨和实践，我们不仅解决了 RAG 应用中的性能问题，还为中大型项目提供了一种高效、可扩展的向量数据存储和管理方案。随着 AI 技术的不断发展，向量数据库在 AIGC 应用架构中的作用将越来越重要，而 Milvus 等向量数据库的选择和应用，将为构建更加智能和高效的 AI 应用提供强有力的支持。

本文所涉及的完整代码在该项目中：https://github.com/xiaobox/llamaindex_test 大家可按需自取

提升RAG应用性能：使用智谱AI的GLM-4和Embedding-3模型优化文档检索

Tue, 08 Oct 2024 07:59:17 +0000

回顾

上文提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析我们介绍了如何通过 DeepSeek 的 API 调用 DeepSeek v2.5 模型替换通过 Ollama 调用本地下载好的 Qwen2.5 模型。

这样做的目的是想通过 API 调用远程部署好的 LLM 给我们的 RAG 应用提提速。不然由于本地个人电脑计算资源的不足（我的电脑没有 GPU）会导致 RAG 应用运行缓慢。

在我们的 RAG 应用中分别使用了两个模型，一个是 embedding 模型，它的作用有这么几点：

文档嵌入（Document Embedding）

表示文档：将文档转换为高维向量（embeddings），这些向量能够捕捉文档的语义信息。
相似度计算：通过计算查询和文档嵌入之间的相似度，找到与查询最相关的文档。

查询嵌入（Query Embedding）

表示查询：将用户的查询转换为高维向量，这些向量能够捕捉查询的语义信息。
检索相关文档：通过计算查询嵌入和文档嵌入之间的相似度，找到与查询最相关的文档

文档检索（Document Retrieval）

高效检索：通过向量数据库（如 Faiss、Annoy 等），快速找到与查询最相关的文档。
相关性排序：根据相似度得分对检索到的文档进行排序，选择最相关的文档作为生成回答的依据。

生成回答（Answer Generation）

融合信息：将检索到的相关文档与查询结合，生成高质量的回答。
上下文感知：利用检索到的文档作为上下文，生成更加准确和丰富的回答。

其中第 4 点，要结合 LLM 来完成。所以这也是我们在 RAG 应用中使用第二个模型–大语言模型（LLM）的意义。

我们再通过回顾 2 张图片来比较直观地了解下 embedding 和 LLM 在 RAG 中的作用：

embedding 过程
RAG

问题

上文遗留的问题很明显，因为我们需要使用的 2 个模型通过 DeekSeek 的 API 只替换了其中的LLM，而 embedding 模型仍然用的是本地的。没有替换是因为 DeepSeek 的 API 不支持：

引自 deepseek 文档

虽然我们下载的 embedding 模型 BAAI/bge-base-zh-v1.5 比较小巧，在本地运行的速度也还行，但我还是想试一下调用远程部署好的更大更优秀的 embedding 模型后会怎样？

于是我将目光转向了另一个很知名，同样很优秀的国产 AI 公司 智谱 AI

智谱 AI

这两年 AI 的发展如火如荼，以 ChatGPT 为代表的一众 AIGC 应用深入人心，这些应用的背后都少不了大语言模型的支持。然而对于国内用户使用这些产品仍然有门槛。大家不禁想找到一个能打的国产 AI 产品。

去年秋天我还在迷信 ChatGPT 的能力是“宇宙无敌”，直到我体验了智谱 AI 旗下的 智谱清言 我才觉得国产 AI 产品在中文语料下的能力并不比别人差。

智谱是由清华大学计算机系技术成果转化而来的公司。它的发展很快。目前可供用户使用的各类模型 20 余个。其中包括：

大规模语言模型 GLM-4
视频生成模型 CogVideoX
代码模型 CodeGeeX-4
图片生成模型 CogView-3
嵌入式模型 Embedding-3
……

智谱在开源领域也做出了极大贡献，上面列举的这些模型都能在 HuggingFace 或 GitHub 上找到开源的版本。

智谱 AI 最让我们熟悉的产品是其 C 端 AIGC 产品 智谱清言

在中文语料下，它的问答质量不比 GPT-4 差！

LlamaIndex 集成 Zhipu embedding

通过查看智谱 AI 大模型开放平台的文档得知它有两款 embedding 模型可以通过 API 调用

于是决定将 Embedding-3 试着集成到 LlamaIndex 中。

当然，调用 API 首先你要有 API Key 以及可用的 tokens，这个我们在之前的文章我介绍过，一般是需要付费的，智谱 AI 会给新老用户赠送一些 tokens，之前赠送给了我 1000w tokens ，所以下面的示例我就用这些免费的 tokens。

简单 demo

我们先根据文档写一个最简单的模型调用 demo

 1from zhipuai import ZhipuAI
 2import os
 3
 4client = ZhipuAI(api_key=os.getenv("GLM_4_PLUS_API_KEY"))
 5response = client.embeddings.create(
 6 model="embedding-3",
 7 input=[
 8 "美食非常美味，服务员也很友好。",
 9 "这部电影既刺激又令人兴奋。",
10 "阅读书籍是扩展知识的好方法。",
11 ],
12)
13print(response)

它响应的输出是这样的：

这输出的一片数字是啥？

这里简单解释一下：嵌入是将文字、图像或其他类型的数据转换成一系列数字（向量）的过程。这个向量在高维空间中代表了原始数据的语义信息。你看到的那一长串数字（如 -0.019210815, -0.0023460388, 0.010299683 等）就是嵌入向量的具体值。每个数字代表向量在某个维度上的值，这些数字虽然看起来没有明显意义，但它们在高维空间中编码了输入文本的语义信息。相似的文本会产生相似的向量，这使得我们可以进行语义相似度比较。这种表示方法使得机器能够更好地"理解"和处理文本数据。

能够正常输出，代表模型调用成功。

和 LlamaIndex 集成

在之前的文章中我们已经通过 Custom LLM 的方式将 LlamaIndex 和 GLM-4 集成在一起了，也就是在 RAG 应用中使用的框架是 LlamaIndex ，调用的 LLM 是 GLM-4。

同理，现在我们要把 embedding 模型也同 LlamaIndex 集成起来，这样我们自己写的这个 RAG 应用的技术组合就是 RAG = LlamaIndex +GLM-4 + Embedding-3

和 LLM 一样，在 LlamaIndex 文档的 embedding 模型兼容列表中并没有 Zhipu 的 Embedding-3 ，仍然需要通过自定义的方式来实现。

这是文档中给的自定义 embedding 的例子：

 1from typing import Any, List
 2from InstructorEmbedding import INSTRUCTOR
 3from llama_index.core.embeddings import BaseEmbedding
 4
 5class InstructorEmbeddings(BaseEmbedding):
 6 def __init__(
 7 self,
 8 instructor_model_name: str = "hkunlp/instructor-large",
 9 instruction: str = "Represent the Computer Science documentation or question:",
10 **kwargs: Any,
11 ) -> None:
12 super().__init__(**kwargs)
13 self._model = INSTRUCTOR(instructor_model_name)
14 self._instruction = instruction
15
16 def _get_query_embedding(self, query: str) -> List[float]:
17 embeddings = self._model.encode([[self._instruction, query]])
18 return embeddings[0]
19
20 def _get_text_embedding(self, text: str) -> List[float]:
21 embeddings = self._model.encode([[self._instruction, text]])
22 return embeddings[0]
23
24 def _get_text_embeddings(self, texts: List[str]) -> List[List[float]]:
25 embeddings = self._model.encode(
26 [[self._instruction, text] for text in texts]
27 )
28 return embeddings
29
30 async def _get_query_embedding(self, query: str) -> List[float]:
31 return self._get_query_embedding(query)
32
33 async def _get_text_embedding(self, text: str) -> List[float]:
34 return self._get_text_embedding(text)

仔细看的话，实际上只需要实现 2 个方法即可，下面的方法都会调用这两个方法：

1 def _get_query_embedding(self, query: str) -> List[float]:
2 embeddings = self._model.encode([[self._instruction, query]])
3 return embeddings[0]
4
5 def _get_text_embedding(self, text: str) -> List[float]:
6 embeddings = self._model.encode([[self._instruction, text]])
7 return embeddings[0]

这里我们可以新建一个自定义的 embedding 类：

 1class ZhipuEmbeddings(BaseEmbedding):
 2 client: ZhipuAI = Field(default_factory=lambda: ZhipuAI(api_key=API_KEY))
 3
 4 def __init__(
 5 self,
 6 model_name: str = "embedding-3",
 7 **kwargs: Any,
 8 ) -> None:
 9 super().__init__(model_name=model_name, **kwargs)
10 self._model = model_name
11
12 def invoke_embedding(self, query: str) -> List[float]:
13 response = self.client.embeddings.create(model=self._model, input=[query])
14
15 # 检查响应是否成功
16 if response.data and len(response.data) > 0:
17 return response.data[0].embedding
18 else:
19 raise ValueError("Failed to get embedding from ZhipuAI API")
20
21 def _get_query_embedding(self, query: str) -> List[float]:
22 return self.invoke_embedding(query)
23
24 def _get_text_embedding(self, text: str) -> List[float]:
25 return self.invoke_embedding(text)
26
27 def _get_text_embeddings(self, texts: List[str]) -> List[List[float]]:
28 return [self._get_text_embedding(text) for text in texts]
29
30 async def _aget_query_embedding(self, query: str) -> List[float]:
31 return self._get_query_embedding(query)
32
33 async def _aget_text_embedding(self, text: str) -> List[float]:
34 return self._get_text_embedding(text)
35
36 async def _aget_text_embeddings(self, texts: List[str]) -> List[List[float]]:
37 return self._get_text_embeddings(texts)

在利用 LlamaIndex 调用时，将 embed_model 设置为自定义类就可以了：

1 # 设置 LLM 和嵌入模型
2 Settings.llm = GLM4LLM()
3 Settings.embed_model = ZhipuEmbeddings()

这样我们的 RAG 应用就把智谱 AI 的 GLM-4 和 Embedding-3 一起使用上了。

以下是完整代码：

 1import os
 2import sys
 3import logging
 4from zhipuai import ZhipuAI
 5from typing import Any, List
 6from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
 7from llama_index.core.embeddings import BaseEmbedding
 8from llama_index.core.llms import (
 9 CustomLLM,
 10 CompletionResponse,
 11 CompletionResponseGen,
 12 LLMMetadata,
 13)
 14from llama_index.core.llms.callbacks import llm_completion_callback
 15from dotenv import load_dotenv
 16from functools import cached_property
 17from pydantic import Field
 18
 19# 配置日志
 20logging.basicConfig(level=logging.INFO)
 21logger = logging.getLogger(__name__)
 22
 23# 从环境变量获取 API 密钥
 24load_dotenv()
 25
 26API_KEY = os.getenv("GLM_4_PLUS_API_KEY")
 27if not API_KEY:
 28 raise ValueError("GLM_4_PLUS_API_KEY environment variable is not set")
 29
 30class GLM4LLM(CustomLLM):
 31 @cached_property
 32 def client(self):
 33 return ZhipuAI(api_key=API_KEY)
 34
 35 @property
 36 def metadata(self) -> LLMMetadata:
 37 return LLMMetadata()
 38
 39 def chat_with_glm4(self, system_message, user_message):
 40 response = self.client.chat.completions.create(
 41 model="glm-4-plus",
 42 messages=[
 43 {
 44 "role": "system",
 45 "content": system_message,
 46 },
 47 {
 48 "role": "user",
 49 "content": user_message,
 50 },
 51 ],
 52 stream=True,
 53 )
 54 return response
 55
 56 @llm_completion_callback()
 57 def complete(self, prompt: str, **kwargs: Any) -> CompletionResponse:
 58 response = self.chat_with_glm4("你是一个聪明的 AI 助手", prompt)
 59 full_response = "".join(
 60 chunk.choices[0].delta.content
 61 for chunk in response
 62 if chunk.choices[0].delta.content
 63 )
 64 return CompletionResponse(text=full_response)
 65
 66 @llm_completion_callback()
 67 def stream_complete(self, prompt: str, **kwargs: Any) -> CompletionResponseGen:
 68 response = self.chat_with_glm4("你是一个聪明的 AI 助手", prompt)
 69
 70 def response_generator():
 71 response_content = ""
 72 for chunk in response:
 73 if chunk.choices[0].delta.content:
 74 response_content += chunk.choices[0].delta.content
 75 yield CompletionResponse(
 76 text=response_content, delta=chunk.choices[0].delta.content
 77 )
 78
 79 return response_generator()
 80
 81class ZhipuEmbeddings(BaseEmbedding):
 82 client: ZhipuAI = Field(default_factory=lambda: ZhipuAI(api_key=API_KEY))
 83
 84 def __init__(
 85 self,
 86 model_name: str = "embedding-3",
 87 **kwargs: Any,
 88 ) -> None:
 89 super().__init__(model_name=model_name, **kwargs)
 90 self._model = model_name
 91
 92 def invoke_embedding(self, query: str) -> List[float]:
 93 response = self.client.embeddings.create(model=self._model, input=[query])
 94
 95 # 检查响应是否成功
 96 if response.data and len(response.data) > 0:
 97 return response.data[0].embedding
 98 else:
 99 raise ValueError("Failed to get embedding from ZhipuAI API")
100
101 def _get_query_embedding(self, query: str) -> List[float]:
102 return self.invoke_embedding(query)
103
104 def _get_text_embedding(self, text: str) -> List[float]:
105 return self.invoke_embedding(text)
106
107 def _get_text_embeddings(self, texts: List[str]) -> List[List[float]]:
108 return [self._get_text_embedding(text) for text in texts]
109
110 async def _aget_query_embedding(self, query: str) -> List[float]:
111 return self._get_query_embedding(query)
112
113 async def _aget_text_embedding(self, text: str) -> List[float]:
114 return self._get_text_embedding(text)
115
116 async def _aget_text_embeddings(self, texts: List[str]) -> List[List[float]]:
117 return self._get_text_embeddings(texts)
118
119# 设置环境变量，禁用 tokenizers 的并行处理
120os.environ["TOKENIZERS_PARALLELISM"] = "false"
121
122def run_glm4_query_with_embeddings(query: str):
123 # 从指定目录加载文档数据
124 documents = SimpleDirectoryReader("data").load_data()
125
126 # 设置 LLM 和嵌入模型
127 Settings.llm = GLM4LLM()
128 Settings.embed_model = ZhipuEmbeddings()
129
130 # 创建索引和查询引擎
131 index = VectorStoreIndex.from_documents(documents)
132 query_engine = index.as_query_engine(streaming=True)
133
134 # 执行查询
135 print("GLM-4 查询结果：")
136 response = query_engine.query(query)
137
138 # 处理并输出响应
139 if hasattr(response, "response_gen"):
140 # 流式输出
141 for text in response.response_gen:
142 print(text, end="", flush=True)
143 sys.stdout.flush() # 确保立即输出
144 else:
145 # 非流式输出
146 print(response.response, end="", flush=True)
147
148 print("\n 查询完成")

效果

从最终的使用效果上看，速度上不如之前使用本地 embedding 模型 BAAI/bge-base-zh-v1.5 快。因为执行了多次 Http 远程调用：

所以我又查了一下文档看看有没有办法提提速：

虽然有一个 dimensions 参数，虽然我感觉设置的越小维度越小数据也越少，那么速度可能更快，但实际测试下来速度并没有明显变化。其主要原因还是：它是同步调用的

看来从 API 上没办法提速了，只能在编程模型上想办法了，这里就不多说了。这里我认为，最好的方式还是在一个资源充足的服务器中部署一个开源的 embedding 模型，这样方便模型的微调及不限量的调用。速度也会快许多

最后

我已将文章中涉及到的相关代码上传至：https://github.com/xiaobox/llamaindex_test

这个仓库中包含了最新几篇文章中的所有 demo 代码，大家可以自行查看。

提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析

Sun, 06 Oct 2024 13:27:10 +0000

概述

在上一篇文章中如何用 30秒和 5 行代码写个 RAG 应用？，我们介绍了如何利用 LlamaIndex 结合 Ollama 的本地大模型和在 Hugging Face 开源的 embedding 模型用几行 Python 代码轻松构建一个 RAG 应用。

从最终输出的结果上看是满意的，理论上是可以针对本地的知识库内容进行精准的问答。然而执行效率却不尽人意。原因是：无论 LLM 还是 embedding 模型的调用都是在本地，而我本地电脑的性能确属一般（几乎只能利用到 CPU 资源，没有 GPU 资源），这样就导致代码运行速度缓慢。

本文我们将介绍，如何通过调用国产大模型 DeepSeek 的 API 为我们的 RAG 应用提速，我们将把对本地 Ollama 的模型调用替换成对 DeepSeek API 的调用。

对比一下上文和本文的方案：

上文：LlamaIndex + Ollama(Qwen2:7b)+ embedding（BAAI/bge-base-zh-v1.5）
本文：LlamaIndex + DeepSeek API + embedding（BAAI/bge-base-zh-v1.5）

DeepSeek

首先来明确几个问题

为什么不用 OpenAI 的 API？

当然可以，而且 LlamaIndex 默认支持的就是通过 API Key 访问 OpenAI 的 API。问题是成本太高了，有更高性价比的所以不用它。

DeepSeek 是什么？

DeepSeek 这个词在不同的上下文中有不同的含义，为了避免概念和语义的混淆，我们在这里分别说明一下：

DeepSeek 代表一个公司：杭州深度求索人工智能基础技术研究有限公司，专注于大模型研发、AI 技术创新和企业解决方案，是幻方量化的子公司。
DeepSeek 代表一个大语言模型 ：具有 236B 参数量（2360 亿个参数）的开源大语言模型。严格上讲，DeepSeek 不只是一个单一的模型，而是包含多个针对不同任务和应用场景的模型系列，这些模型在 DeepSeek 的基础上进行了专门的优化和训练，以满足特定的需求，如：DeepSeek-Chat、 DeepSeek-Math、DeepSeek-Coder 等。
DeepSeek 是一个 API: 由 DeepSeek 公司开发对外提供付费的大模型功能的接口，支持文本生成、对话系统、文本摘要、问答系统和多模态任务等。

在本文中，我们利用 DeepSeek 的 API 间接调用 DeepSeek 所提供的模型，具体模型是 DeepSeek V2.5(DeepSeek V2 Chat 和 DeepSeek Coder V2 两个模型已经合并升级，升级后的新模型为 DeepSeek V2.5)

为什么用 DeepSeek ？

使用 DeepSeek 主要出于成本和效果的综合考虑。

虽然 DeepSeek 是开源大模型（在大模型领域，类似这样的国产中文开源大模型还有许多），但是部署这样的具有大规模参数的模型是需要很多硬件资源的，我们手上的个人电脑没有这个条件。更别说运维和微调这样的模型。所以通过 API 直接调用已经部署好的模型是最便捷的方式，当然，这是有成本的，人家部署和运维这样规模的模型也是需要成本的，所以这些 API 是需要付费使用的。

从成本考量，DeepSeek 几乎是最佳方案，因 DeepSeek API 调用价格之便宜曾被戏称为 “AI 界的拼多多”。在 DeepSeek 价格公开后不久，多家模型厂商卷入价格战，现在的模型调用价格是真真正正的被 “打下来”了。多家公司频繁更新自家模型价格，截止目前，可以说 “没有最低，只有更低”。

从效果考量 ，因之前使用过 deepseek-coder、和 deepseek-chat 两个模型，效果上可以说是在中文模型领域的第一梯队。当然这只是我个人的使用体验。

从权威的角度，通过 LMSYS Chatbot Arena Leaderboard（LMSYS Chatbot Arena Leaderboard 是一个大型语言模型的评测排行榜，提供了一个匿名竞技场，用于评估和比较不同模型的性能。）这个大型语言模型的评测排行榜可以了解 DeepSeek 的能力如何

最近的几个月里，国产模型中与 DeepSeek 排名竞争最激烈的是阿里的 Qwen2.5

DeepSeek 的使用费用

前文中我们提到 DeepSeek 的 API 是需要付费调用的，所以到底收多少钱是一个关键的问题。

首先，如果你是一个新用户，那么 DeeepSeek 会送你 500w 个 tokens （在自然语言处理中，Token 是指将文本分割成的最小单位。这些单位可以是单词、子词、字符等，具体取决于所使用的分词策略）。简单理解就是 500w 个字。需要注意的是，送的 tokens 有有效期，一个月后就过期了。

其次，如果送的 tokens 用完了，就需要花真金白银去充值了。

简单说， 10 元 500w tokens，如果你是个人使用，一个人放开了用，一个月足够了。

DeepSeek API 的使用

无论是通过赠送还是付费，当你拥有了 tokens，你就可以根据文档创建自己的 API key 并进行 API 调用了。

由于是走网络 API 的这种方式，在编程语言上就没有限制了，你可以选用你觉得合适的语言。DeepSeek 官方也比较贴心的给出了各种语言调用的示例：

这里我用 Python 写了一个简单的调用 Demo，以下是具体代码：

 1from openai import OpenAI
 2
 3class DeepSeekChat:
 4 def __init__(self, api_key, base_url="https://api.deepseek.com"):
 5 self.client = OpenAI(api_key=api_key, base_url=base_url)
 6
 7 def chat(
 8 self,
 9 system_message,
10 user_message,
11 model="deepseek-chat",
12 max_tokens=1024,
13 temperature=0.7,
14 stream=True,
15 ):
16
17 response = self.client.chat.completions.create(
18 model=model,
19 messages=[
20 {"role": "system", "content": system_message},
21 {"role": "user", "content": user_message},
22 ],
23 max_tokens=max_tokens,
24 temperature=temperature,
25 stream=stream,
26 )
27
28 if stream:
29 return self._stream_response(response)
30 else:
31 return response.choices[0].message.content
32
33 def _stream_response(self, response):
34 full_response = ""
35 for chunk in response:
36 if chunk.choices[0].delta.content is not None:
37 content = chunk.choices[0].delta.content
38 print(content, end="", flush=True)
39 full_response += content
40 
41 print("\r\n===============我是分隔线===============")
42 return full_response
43
44# 使用示例
45if __name__ == "__main__":
46 deepseek_chat = DeepSeekChat(api_key="[你的 API Key]")
47 response = deepseek_chat.chat(
48 system_message="你是一个聪明的 AI 助手",
49 user_message="三国演义中战斗力排名前 10 的武将有谁？",
50 stream=True,
51 )
52 print("完整回答：", response)

可以看到我们只引入了 openai 这一个库，原因是 DeepSeek 的 API 和 OpenAI 的 API 是兼容的。

“

DeepSeek API 使用与 OpenAI 兼容的 API 格式，通过修改配置，您可以使用 OpenAI SDK 来访问 DeepSeek API，或使用与 OpenAI API 兼容的软件。
1 --源自 DeepSeek 文档

引入 openai 这个库以后我们不需要再引入其他多余的库就可以进行 API 请求了。

这段代码比较简单，我的问题是：“三国演义中战斗力排名前 10 的武将有谁？” 我们来看一下大模型给我的回答：

已关注

Replay Share Like

观看更多

退出全屏

切换到竖屏全屏**退出全屏

小盒子的技术分享已关注

Share Video

，时长00:19

0/0

00:00/00:19

切换到横屏模式

继续播放

进度条，百分之0

Play

00:00

00:19

倍速

全屏

倍速播放中

0.5倍 0.75倍 1.0倍 1.5倍 2.0倍

超清流畅

Your browser does not support video tags

继续观看

提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析

观看更多

Original

提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析

小盒子的技术分享已关注

Share点赞Wow

Added to Top StoriesEnter comment

Video Details

RAG

在上一篇文章中我们能够方便地调用 Ollama 进而调用本地下载好的模型，是因为 LlamaIndex 的库封装好了：

1# 设置语言模型，使用 Ollama 提供的 Qwen2 7B 模型，并设置请求超时时间
2Settings.llm = Ollama(model="qwen2:7b", request_timeout=360.0)

现在，我们想用在线的模型 DeepSeek，让 LlamaIndex 去调用 DeepSeek API 就不能用之前的方式了。

LlamaIndex 支持的 LLM 集成方式

通过查看 LlamaIndex 的文档，总结来说，它支持的 LLM 集成方式有三种：

通过 Ollama 调用安装在本地的大模型（一般适用于个人电脑使用）
通过 API 调用的免费或付费模型
自定义 LLM

我们需要解释一下：

第一种方式 : Ollama 无需多言。
第二种方式 : API 付费调用不是所有市面上的模型 LlamaIndex 都有现成的集成方式，比如 DeepSeek 就没有，具体支持集成哪些模型，在它的文档中有清单：https://docs.llamaindex.ai/en/stable/module_guides/models/llms/modules/ 另外，对于付费模型，模型背后的公司都会提供相应的 API，付费购买就可以了，而开源模型虽然本身代码是开源的，但提供模型调用服务的平台是收费的，比如 Replicate

也就是说第二种方式无论你使用的模型本身是否开源，提供模型调用服务的平台都会收费。
第三种方式：自定义 LLM，本文我们使用的就是这种方式，这种集成实现方式是 LlamaIndex 留给开发者的一个扩展，我们可以自定义自己需要使用的 LLM 与 LlamaIndex 进行集成。使用这种方式可以实现两类集成：
第一类就是类似 DeepSeek 这种已经有 API 但 LlamaIndex 尚未支持的 LLM。
第二类就是调用我们本地部署的开源大模型，当然一般是部署在服务器上（如果 PC 有足够的计算资源也可以部署在 PC 上）

Custom LLM

如何通过 Custom LLM 的方式将 DeepSeek 与 LlamaIndex 进行集成呢？

其实很容易，我们只需要创建一个类并实现三个方法即可（用 python 代码实现）。

文档中给出的代码是这样的：

 1from typing import Optional, List, Mapping, Any
 2
 3from llama_index.core import SimpleDirectoryReader, SummaryIndex
 4from llama_index.core.callbacks import CallbackManager
 5from llama_index.core.llms import (
 6 CustomLLM,
 7 CompletionResponse,
 8 CompletionResponseGen,
 9 LLMMetadata,
10)
11from llama_index.core.llms.callbacks import llm_completion_callback
12from llama_index.core import Settings
13
14class OurLLM(CustomLLM):
15 context_window: int = 3900
16 num_output: int = 256
17 model_name: str = "custom"
18 dummy_response: str = "My response"
19
20 @property
21 def metadata(self) -> LLMMetadata:
22 """Get LLM metadata."""
23 return LLMMetadata(
24 context_window=self.context_window,
25 num_output=self.num_output,
26 model_name=self.model_name,
27 )
28
29 @llm_completion_callback()
30 def complete(self, prompt: str, **kwargs: Any) -> CompletionResponse:
31 return CompletionResponse(text=self.dummy_response)
32
33 @llm_completion_callback()
34 def stream_complete(
35 self, prompt: str, **kwargs: Any
36 ) -> CompletionResponseGen:
37 response = ""
38 for token in self.dummy_response:
39 response += token
40 yield CompletionResponse(text=response, delta=token)
41
42# define our LLM
43Settings.llm = OurLLM()
44
45# define embed model
46Settings.embed_model = "local:BAAI/bge-base-en-v1.5"
47
48# Load the your data
49documents = SimpleDirectoryReader("./data").load_data()
50index = SummaryIndex.from_documents(documents)
51
52# Query and print response
53query_engine = index.as_query_engine()
54response = query_engine.query("<query_text>")
55print(response)

OurLLM 就是要创建的类，要实现的三个方法是：

metadata
complete
stream_complete

实际上一般 metadata 方法可以直接返回 LLMMetadata() ，最主要的就是实现后面两个方法。

实例

根据上一节 Custom LLM 所述，我将上一篇文章中的 Ollama 模型调用换成自定义的 DeepSeek，以下是主要代码：

 1import os
 2import sys
 3import logging
 4from openai import OpenAI
 5from typing import Any, Generator
 6from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
 7from llama_index.embeddings.huggingface import HuggingFaceEmbedding
 8from llama_index.core.llms import (
 9 CustomLLM,
 10 CompletionResponse,
 11 CompletionResponseGen,
 12 LLMMetadata,
 13)
 14from llama_index.core.llms.callbacks import llm_completion_callback
 15from pydantic import BaseModel, Field
 16from dotenv import load_dotenv
 17from functools import cached_property
 18
 19# 配置日志 创建一个与当前模块同名的 logger
 20logging.basicConfig(level=logging.INFO)
 21logger = logging.getLogger(__name__)
 22
 23# 从环境变量获取 API 密钥
 24load_dotenv()
 25
 26API_KEY = os.getenv("DEEPSEEK_API_KEY")
 27if not API_KEY:
 28 raise ValueError("DEEPSEEK_API_KEY environment variable is not set")
 29
 30class DeepSeekChat(BaseModel):
 31 """DeepSeek 聊天模型的封装类。"""
 32
 33 api_key: str = Field(default=API_KEY)
 34 base_url: str = Field(default="https://api.deepseek.com")
 35
 36 class Config:
 37 """Pydantic 配置类。"""
 38
 39 arbitrary_types_allowed = True # 允许模型接受任意类型的字段
 40 # 这增加了灵活性，但可能降低类型安全性
 41 # 在本类中，这可能用于允许使用 OpenAI 客户端等复杂类型
 42
 43 @cached_property
 44 def client(self) -> OpenAI:
 45 """创建并缓存 OpenAI 客户端实例。"""
 46 return OpenAI(api_key=self.api_key, base_url=self.base_url)
 47
 48 def chat(
 49 self,
 50 system_message: str,
 51 user_message: str,
 52 model: str = "deepseek-chat",
 53 max_tokens: int = 1024,
 54 temperature: float = 0.7,
 55 stream: bool = False,
 56 ) -> Any:
 57 """
 58 使用 DeepSeek API 发送聊天请求。
 59
 60 返回流式响应或完整响应内容。
 61 """
 62 try:
 63 response = self.client.chat.completions.create(
 64 model=model,
 65 messages=[
 66 {"role": "system", "content": system_message},
 67 {"role": "user", "content": user_message},
 68 ],
 69 max_tokens=max_tokens,
 70 temperature=temperature,
 71 stream=stream,
 72 )
 73 return response if stream else response.choices[0].message.content
 74 except Exception as e:
 75 logger.error(f"Error in DeepSeek API call: {e}")
 76 raise
 77
 78 def _stream_response(self, response) -> Generator[str, None, None]:
 79 """处理流式响应，逐块生成内容。"""
 80 for chunk in response:
 81 if chunk.choices[0].delta.content is not None:
 82 yield chunk.choices[0].delta.content
 83
 84class DeepSeekLLM(CustomLLM):
 85 """DeepSeek 语言模型的自定义实现。"""
 86
 87 deep_seek_chat: DeepSeekChat = Field(default_factory=DeepSeekChat)
 88
 89 @property
 90 def metadata(self) -> LLMMetadata:
 91 """返回 LLM 元数据。"""
 92 return LLMMetadata()
 93
 94 @llm_completion_callback()
 95 def complete(self, prompt: str, **kwargs: Any) -> CompletionResponse:
 96 """执行非流式完成请求。"""
 97 response = self.deep_seek_chat.chat(
 98 system_message="你是一个聪明的 AI 助手", user_message=prompt, stream=False
 99 )
100 return CompletionResponse(text=response)
101
102 @llm_completion_callback()
103 def stream_complete(self, prompt: str, **kwargs: Any) -> CompletionResponseGen:
104 """执行流式完成请求。"""
105 response = self.deep_seek_chat.chat(
106 system_message="你是一个聪明的 AI 助手", user_message=prompt, stream=True
107 )
108
109 def response_generator():
110 """生成器函数，用于逐步生成响应内容。"""
111 response_content = ""
112 for chunk in self.deep_seek_chat._stream_response(response):
113 if chunk:
114 response_content += chunk
115 yield CompletionResponse(text=response_content, delta=chunk)
116
117 return response_generator()
118
119# 设置环境变量，禁用 tokenizers 的并行处理，以避免潜在的死锁问题
120os.environ["TOKENIZERS_PARALLELISM"] = "false"
121
122def main():
123 """主程序函数，演示如何使用 DeepSeekLLM 进行文档查询。"""
124 # 从指定目录加载文档数据
125 documents = SimpleDirectoryReader("data").load_data()
126
127 # 设置 LLM 和嵌入模型
128 Settings.llm = DeepSeekLLM()
129 Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-base-zh-v1.5")
130
131 # 创建索引和查询引擎
132 index = VectorStoreIndex.from_documents(documents)
133 query_engine = index.as_query_engine(streaming=True)
134
135 # 执行查询
136 print("查询结果：")
137 response = query_engine.query("作者学习过的编程语言有哪些？")
138
139 # 处理并输出响应
140 if hasattr(response, "response_gen"):
141 # 流式输出
142 for text in response.response_gen:
143 print(text, end="", flush=True)
144 sys.stdout.flush() # 确保立即输出
145 else:
146 # 非流式输出
147 print(response.response, end="", flush=True)
148
149 print("\n 查询完成")
150
151if __name__ == "__main__":
152 main()

你别看代码写的长，那是因为我做过重构，其实可以实现的更短。不要被篇幅吓到，其实主要执行逻辑与上一篇文章中写的没什么区别，只在自定义 DeepSeekLLM 这里有所不同，如果你把本文从头看到尾，其实其中的第一步分解拆开都有解释过，也比较简单。

我们来看一下效果，测试数据仍然是上一篇文章中的文本内容，问题仍然是：“作者学习过的编程语言有哪些？”

已关注

Replay Share Like

观看更多

退出全屏

切换到竖屏全屏**退出全屏

小盒子的技术分享已关注

Share Video

，时长00:09

0/0

00:00/00:09

切换到横屏模式

继续播放

进度条，百分之0

Play

00:00

00:09

倍速

全屏

倍速播放中

0.5倍 0.75倍 1.0倍 1.5倍 2.0倍

超清流畅

Your browser does not support video tags

继续观看

提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析

观看更多

转载

提速 RAG 应用：用 DeepSeek API 替换本地 Ollama 模型，LlamaIndex 实战解析

小盒子的技术分享已关注

Share点赞Wow

Added to Top StoriesEnter comment

Video Details

总结

本文我们介绍了如何通过调用国产大模型 DeepSeek 的 API 来提升 RAG（检索增强生成）应用的执行效率。相比使用本地 Ollama 模型，DeepSeek 的 API 不仅解决了本地计算资源不足导致的运行速度慢的问题，还保持了高质量的生成结果。DeepSeek 在成本和效果上表现出色，特别适合中文模型的应用。通过自定义 LLM 的方式，我们成功将 DeepSeek 与 LlamaIndex 集成，展示了如何实现高效的数据处理和生成。本文提供的方法和示例代码为构建高性能 RAG 应用提供了一种实用的解决方案。