DevOps on 小盒子的技术分享

我用两句中文，让 Claude Code 帮我画了10张出版级技术图

Sun, 12 Apr 2026 08:38:12 +0000

前两天在写一篇技术文章，写到一半需要配一张微服务架构图。我打开了某在线画图工具，对着空白画布发了十分钟的呆，拖了两个方块，连了一条线，觉得丑，删掉，再拖两个方块。

半小时过去了，图还没画完，文章的灵感已经凉透了。

我相信很多搞技术内容的朋友都有过这种体验。你脑子里其实很清楚这张图应该长什么样，但你就是得花一两个小时在画图工具里对齐、配色、调字号。明明内容才是核心，结果时间全花在了排版上。

然后我发现了一个东西，彻底解决了这个问题。

它叫 fireworks-tech-graph，是一个 Claude Code 的 skill。装上之后，你跟 Claude Code 说一句中文，它就能给你吐出一张出版级别的技术图。SVG 矢量源文件加 1920px 高清 PNG，直接能往文章里塞。

我用它画了10张不同类型的图，从架构图到 ER 图到状态机，从白底极简到暗色霓虹到工程蓝图。每张图从下指令到拿到成品 PNG，平均不超过30秒。

30秒。

我之前在画图工具里对齐一个箭头的时间都不止30秒。

怎么装呢，你甚至不需要记任何命令。

打开 Claude Code，直接跟它说「帮我安装 fireworks-tech-graph 这个 skill」，它自己就把活干了。装完之后你说「画一个 xxx 图」，它就自动触发。

如果你喜欢手动装也行，就一句 claude skills install fireworks-tech-graph，完事。

触发词非常宽泛，「画图」「帮我画」「做个架构图」「生成一个流程图」「可视化一下」，随便怎么说都行，它都能识别。

它能画什么？

这个 skill 支持10种有模板的图表类型，外加4种无模板但有规则定义的类型。我挑几个最实用的说一下。

1，架构图。这是用得最多的，画微服务分层、系统组件关系。你告诉它有哪些服务、怎么分层、哪些组件之间有调用关系，它自动帮你排好。我画的那张微服务架构图有5层，右侧还挂了一个观测性旁路，出来的效果跟正经架构文档里的图一模一样。

2，流程图。CI/CD 流水线、审批流、业务决策流。菱形判断节点、圆角矩形处理步骤、失败回环，全都有。你只需要描述「从提交代码到部署生产」中间经过哪些步骤和判断就行。

3，时序图。微服务之间谁先调谁，消息怎么传递。标准的 UML 时序图，有生命线、激活框、alt 分组框。你列出参与者和消息序列，它帮你排好。

4，ER 图。数据库表之间的关系。支持鸦脚记法，PK 自动下划线，FK 标注。你把实体和属性列出来，告诉它哪些是一对多、哪些是多对多，它画出来的东西可以直接放进数据库设计文档。

5，状态机。订单生命周期、工单状态流转这种。每个状态是一个圆角矩形，转换线上标事件名，有初始态的实心圆和终态的同心圆。

6，对比矩阵。横评几个模型、几个方案的时候特别好使。我画了一张 LLM 模型对比表，5个模型7个维度，绿色打勾红色打叉，交替行填充，出来就是一张可以直接发朋友圈的表。

7，时间线。项目路线图、版本规划。甘特图样式，彩色横条加菱形里程碑。

除了这些，还有 Agent 架构图、用例图、数据流图。反正你在技术写作里能用到的图，它基本都覆盖了。

比较骚的是它有7种视觉风格，每种味道完全不一样。

默认的 Flat Icon 是白底彩色，适合博客和文档。Dark Terminal 是暗色霓虹风，发 GitHub 和技术社区特别帅。Blueprint 是工程蓝图风，深蓝色背景加网格线加角标，那种 CAD 图纸的感觉。Notion Clean 是极简白，一根线一个色。Glassmorphism 是毛玻璃卡片，适合产品官网和 Keynote。最近还加了 Claude Official 和 OpenAI Official 两种风格，分别是 Anthropic 和 OpenAI 的品牌调性。

你指定风格的方式就是在 prompt 里加一句「用蓝图风」或者「Style 3」，就这么简单。

我觉得这个 skill 最打动我的点，不是它画得多漂亮，而是它把「画图」这件事的心理门槛降到了零。以前我写文章需要配图的时候，经常会想「算了这里用文字描述一下也行吧」，因为打开画图工具、画完、导出、插入这一套流程太重了。现在不一样了，我在 Claude Code 里写着文章，写到需要配图的地方，直接说一句「帮我画一个 xxx」，30秒后图就在本地了。

这种体验就像是，你本来在用文本编辑器写代码，突然有人给你装了一个实时预览插件。功能上没变，但那个「随时能看到效果」的即时反馈感，会让你更愿意去做这件事。

画图也是一样。当成本足够低的时候，你会发现你开始「想画就画」了。

想试的朋友，打开 Claude Code，说一句「帮我安装 fireworks-tech-graph」，等它装完，再说一句「画一个 xxx 图」。

就这么简单。两句话的事。

下面附一些 demo 图：

OpenAI 开源 Symphony：AI 不再只是写代码，而是开始接管“工作流”

Sat, 07 Mar 2026 11:39:53 +0000

最近跟业界一些朋友交流，不少公司正在做内部软件开发的 AI 自动化流程系统，正好这两天，OpenAI 在 GitHub 上低调开源了一个很值得认真看的项目：Symphony。

如果只看名字，你很容易把它理解成“又一个多 Agent 编排框架”；但只要认真读完 README、SPEC.md 和参考实现里的 WORKFLOW.md，你会发现它真正想解决的，根本不是“让 AI 会写代码”，而是另一件更大的事：

如何把软件研发中的“工作”，交给一套可以持续运行、可隔离、可调度、可回收、可观测的系统去推进。

这就是 Symphony 最重要的定位。官方原话非常值得细品：

它会把项目工作转成 isolated, autonomous implementation runs，让团队从“监督 coding agents”转向“管理 work”。README 里的 demo 也很直白：Symphony 盯着 Linear 看板拿任务，拉起 agent 处理 issue，回传 CI 状态、PR review 反馈、复杂度分析和 walkthrough 视频，最后在被接受后安全落 PR。

很多人第一次看到这里，会本能地把它和 Copilot、Cursor、Claude Code 之类工具放在一起比较。但我觉得，真正准确的比较方式不是“谁代码写得更强”，而是：谁更接近一个面向研发现场的执行系统。 Copilot 类产品解决的是“我写代码时，旁边有个聪明助手”；Symphony 想解决的是“我有一堆 issue，能不能让系统自己取单、分配环境、拉起 Agent、推进状态、处理失败、保留上下文，并把结果交回给我验收”。这已经不只是“辅助编码”，而是开始触碰软件交付流水线本身。

一、Symphony 到底是什么？

从 SPEC.md 看，Symphony 的定义非常清晰：它是一个 long-running automation service。在当前规范版本里，它会持续从 issue tracker 读取工作（v1 里明确是 Linear），为每个 issue 创建独立 workspace，并在这个 workspace 里运行 coding agent session。规范还特别强调了它要解决的四类问题：

1.把 issue 执行变成守护式工作流

2.把每个任务隔离到独立 workspace

3.把工作流策略放回 repo 内的 WORKFLOW.md

4.以及为多任务并发运行提供足够的 observability。

这段定义很重要，因为它一下子把 Symphony 和大量“Agent Demo”拉开了距离。它不是一个写几个 prompt、串几个工具的 toy project，也不是一个单轮任务脚本。它有轮询、有调度、有状态机、有重试退避、有 workspace 生命周期、有运行期事件、有恢复逻辑。换句话说，它的思维方式更像一个 orchestrator，而不是一个单纯的 agent wrapper。

更关键的是，SPEC 还专门写了一个“重要边界”：Symphony 是 scheduler/runner 和 tracker reader。这句话很克制，也很专业。它的意思是，Symphony 的职责重点不是替你定义所有业务流程，而是负责任务编排、执行承载和状态协调；而 ticket 状态变更、评论、PR 链接等写操作，通常还是由 coding agent 借助工具在运行时完成。也就是说，它不是一个万能 PM 系统，而是一层面向软件交付的 agent orchestration 壳。

二、它为什么比“会写代码”更进一步？

因为真正麻烦的，从来不是 AI 能不能生成一段代码，而是几十个任务并行推进时，系统怎么不失控。

Symphony 在这方面做得非常工程化。它有明确的内部状态机：Unclaimed、Claimed、Running、RetryQueued、Released。它还定义了 run attempt 的阶段：准备 workspace、构建 prompt、拉起 agent 进程、初始化 session、流式执行 turn、结束、成功、失败、超时、卡死、被 reconciliation 取消。它甚至规定了每次 poll tick 到来时，先 reconciliation，再校验配置，再拉候选 issue，再按优先级分发，最后通知 observability 消费者。

这套设计背后的思想可以概括成一句话：

不要先问“怎么让 Agent 跑起来”，而要先问“怎么避免它跑重、跑错、跑飞”。

比如 candidate selection 里就有一条很像真实研发现场的规则：如果 issue 还处于 Todo，而它依赖的 blocker 还没进入终态，那就不要派发。排序也不是瞎来，而是按 priority、创建时间、issue 标识顺序稳定分发。失败之后也不是简单重试，而是区分正常退出后的短延迟 continuation retry 和异常退出后的指数退避重试。这样的设计，明显已经不是“写代码助手”的思路，而是“任务执行系统”的思路。

三、每个 issue 一个 workspace：这是 Symphony 最值钱的工程细节

如果你只让我挑 Symphony 里最关键的一点，我会选这个：per-issue workspace。

SPEC 写得非常清楚：

每个 issue 的 workspace 路径都必须位于配置的 workspace root 之下；coding agent 只能在该 issue 的 workspace 里执行；workspace 目录名必须净化；还支持 after_create、before_run、after_run、before_remove 等 hooks。工作区会跨运行复用，但终态 issue 可以在启动或状态变更时清理。

**为什么这个设计这么重要？**因为一旦没有隔离，Agent 系统很快就会碰到三个问题：上下文污染、任务互相踩踏、失败后难以恢复。Symphony 的思路很像给每个工单都分配一个独立工位，Agent 只能在自己的工位里思考、改代码、跑测试、记录状态。哪怕它中途失败了，下次重试回来，也可以在同一个 workspace 上继续，而不是重新失忆。

这也是为什么我说 Symphony 更接近“工程执行系统”而不是“聊天式 Agent”。聊天系统强调对话连续；Symphony 强调的是任务连续性。这两个东西，根本不是一个层级。

四、WORKFLOW.md 才是灵魂：把 Prompt 升级成 repo 内契约

Symphony 很聪明的一点，是它没有把流程硬编码进平台，而是把策略收回到仓库里。SPEC 规定 WORKFLOW.md 由 YAML front matter 和 Markdown prompt body 组成，运行时会解析出 config 与 prompt template；很多核心行为——轮询间隔、workspace root、并发限制、hooks、agent 参数——都来自这份 repo-owned contract。

参考实现里的 WORKFLOW.md 更是把这种思想写得非常彻底。它规定了 issue 在不同状态下该怎么流转：

●Todo 要立即切到 In Progress，然后找或建唯一的 ## Codex Workpad 评论，再开始分析与实现；

●Human Review 阶段不再改代码，只轮询 review 结果；

●进入 Merging 后必须走专门的 land 技能，不能直接 gh pr merge。文档还要求把单个 workpad comment 当作进度和交接的唯一真相源，并且把 out-of-scope 改进拆成新的 Backlog issue，而不是在当前任务里偷偷扩 scope。

这件事的意义非常大。它意味着团队以后真正需要打磨的，不只是“怎么写 prompt”，而是“怎么把流程、约束、验收标准、状态流转、回退机制，写成一份和代码一起版本化的工程契约”。这比 prompt engineering 更接近组织能力。

五、为什么参考实现偏偏选了 Elixir？

这不是噱头，反而是我觉得 Symphony 最有工程味的地方之一。

GitHub 仓库当前语言分布里，Elixir 约占 94.9%；README 也直接写了 Why Elixir?：因为 Elixir 运行在 Erlang/BEAM/OTP 之上，很适合监督长时间运行的进程，并且支持在不停止活跃 subagents 的情况下做 hot code reloading。

这和 Symphony 的问题形态是高度匹配的。一个普通 Web 请求可能几十毫秒就结束，但一个 coding agent 处理复杂任务时，可能会持续很久，还要接收事件、处理重试、维持会话、更新状态、暴露观测数据。BEAM/OTP 擅长的，恰好就是这种长生命周期、并发多、失败要可控隔离的系统。OpenAI 官方没有在 README 里展开讲 supervision tree 这些词，但它给出的理由已经足够说明方向：Symphony 不是在追求“AI 生态默认语言”，而是在追求“最适合承载 agent orchestration 的运行时”。

六、真正的前提不是更强模型，而是 Harness Engineering

如果说 Symphony 讲的是“如何调度 Agent”，那 Harness Engineering 讲的就是“怎样让 Agent 值得被调度”。

OpenAI 在官方文章里把这件事说得很重：他们构建的产品里，应用逻辑、测试、CI、文档、可观测性和内部工具，全部由 Codex 写出；而人类工程师的角色，从直接写代码，转向设计环境、明确意图、构建反馈回路。文章里那句“Humans steer. Agents execute.”，几乎可以看作整个 Symphony 时代的软件工程宣言。

也正因如此，README 才会明确写：Symphony 最适合已经采用 harness engineering 的代码库。意思很简单：如果你的仓库没有可靠测试、没有清晰边界、没有稳定构建入口、没有可验证的反馈回路，那么再强的 Agent 也只是更快地在混乱里打转。Symphony 的价值，不是替代工程纪律；恰恰相反，它会把工程纪律的重要性放大十倍。

七、它的边界也必须讲清楚

一个成熟的技术判断，不能只讲想象力，不讲边界。

Symphony 现在仍是一个工程预览版，README 明确写了适用于 trusted environments；SPEC 也写了 approval policy、sandbox policy、operator confirmation posture 都是 implementation-defined，不同实现可以高信任，也可以更严格。它当前规范版本只定义了 Linear 作为 tracker，至于更多 issue tracker 适配器，还是 TODO。参考实现虽然带可选 Phoenix observability 服务和 JSON API，但整个项目还远没到“所有团队直接开箱上生产”的阶段。

所以，最稳妥的结论不是“研发彻底无人化已经到来”，而是：

OpenAI 正在把 AI Coding 从“单点能力演示”推进到“工程系统形态演示”。

这一步，比单纯再出一个更强的代码模型，更值得关注。

结语

如果一定要用一句话概括 Symphony，我会这样说：

它不是在教 Agent 如何写代码，而是在教团队如何把“软件交付”本身改写成一套可执行、可编排、可观测的系统。

过去，AI 是工程师的副驾驶；现在，Symphony 展示的是另一种可能：工程师不再盯着每一行代码，而是站到更高一层，去设计流程、约束环境、设定验收标准，然后管理一批持续运行的 agent 去推进工作。真正的变化，不是“AI 会不会写 CRUD”，而是“软件组织会不会因此改写自己的工作方式”。

这，才是 Symphony 最值得认真读的地方。

提示词缓存:让 LLM 成本降 10 倍

Mon, 29 Dec 2025 05:37:52 +0000

“

OpenAI 和 Anthropic 声称，缓存的输入 token 在成本上比常规输入 token 便宜 10 倍。

到底什么是 Cached Token ？

Cached Token 就是让 AI “记住” 它刚刚读过的长内容，不用每次都在脑子里从头重新算一遍，从而让回答变得极快且极便宜。

想象你正在参加一场开卷考试，考试内容是一本 500 页的历史书。

没有 Cache (传统模式) ：
第一题：你把书从第 1 页读到第 500 页，然后回答问题。
第二题：你忘光了刚才读的内容，必须再次从第 1 页读到第 500 页，才能回答第二个问题。
后果：每次回答都很慢，而且把你累得半死（消耗算力，费钱）。
有了 Cached Token (缓存模式) ：
第一题：你从第 1 页读到第 500 页，并把关键知识点和理解暂时存在脑子里（存入显存）。
第二题：你直接调用脑子里的记忆，跳过阅读过程，立刻回答问题。
后果：只有第一次慢，后面飞快，而且因为不用重复劳动，甚至可以给考官（用户）打个一折的优惠价

很多人会误以为 “缓存 = 把上次的回复存起来再发一遍”。不是的。

更准确地说，缓存的是模型在处理这段输入时产生的一些中间计算结果（常被称为 KV cache：attention 里的 K / V 矩阵）。所以即使 cached_tokens 很高，你也仍然可能得到不同的回答（因为采样、temperature 等发生在更后面）

LLM 架构

想要彻底弄明白 Cached Token，我们需要从原理上了解一下 LLM 架构。

我们可以将大语言模型（LLM）的架构看作是一个巨大的数学函数：输入一串数字，输出一个数字。这个过程主要由以下四个核心部分组成：

Tokenizer (分词器 / 切词器)

这是模型与人类语言交互的翻译官。

LLM 无法直接理解文本（如中文或英文），它只能处理数字。Tokenizer 的作用是将你输入的提示词（Prompt）切分成一个个小的片段，称为 Token，并为每个 Token 分配一个唯一的整数 ID。

比如输入 “Check out ngrok.ai”，Tokenizer 会将其切分为 [“Check”, “out”, “ng”, “rok”, “.ai”]，并转换为对应的数字序列。

注意：不同的模型（如 GPT-5 和 Claude）使用不同的 Tokenizer 规则

Embedding (嵌入层)

这是让数字拥有含义的一步。将 Tokenizer 生成的简单整数 ID 转换为高维向量（即一长串数字数组）。这个过程就像查字典，每个 Token ID 对应一个固定的向量。

下面是一个例子，可以看到将原始 token 进行 embedding 后是什么样子。

Embedding 是可以有很多维度的，最大的模型甚至超过 10,000 维，上面的例子只显示了三维。维度越多，大语言模型对每个标记的表示就越复杂、越细致。

这些向量代表了 Token 的 “语义位置”。在这个高维空间中，含义相似的词（如 “猫” 和 “狗”）在空间上的距离会更近。这一步还会把 Token 的位置信息编码进去，这样模型就能知道词语的先后顺序。

如果你听说过 “余弦相似度”，那么恭喜你找对了方向。Embedding（嵌入）和 Cosine Similarity（余弦相似度）的关系可以理解为 “坐标” 与 “距离测量工具” 的关系。

想象一个巨大的多维空间（就像一个无限大的图书馆）。Embedding 就是把每一个词、每一句话都变成这个空间里的一个具体的坐标点，在这个空间里，意思相近的词（比如 “猫” 和 “小猫”），它们的坐标点会靠得很近；意思无关的词（比如 “猫” 和 “微波炉”），距离就会很远。Embedding 把文字变成了数学空间里的向量，而余弦相似度用来计算这些向量之间的 “语义距离”。

Transformer (变换器 / 核心处理层)

这是 LLM 的大脑，负责理解和推理。

它的主要工作是让输入序列中的每个 Token 相互 “交流”。模型会计算每个 Token 对其他 Token 的重要程度（即 “注意力权重”）。例如在句子 “Mary had a little lamb” 中，模型会计算出 “Mary” 对 “had” 的生成有多重要。这就是它的核心机制。

到这里我知道你肯定会想到这篇开山之作**《Attention Is All You Need》**。没错，这篇论文作为开山之作，几乎全篇都在讨论 “Transformer”。该论文提出的 Transformer 架构，其主要职责就是接收 Embedding 层的输入（一堆数字向量），然后在这一层内部通过 Attention（注意力机制）和 Feedforward（前馈网络）对这些数据进行复杂的数学变换。关于论文这里不便展开，我们言归正传。

在这一层，输入的 Embedding 会被转化为 Query (Q)、Key (K) 和 Value (V) 三种形态。通过复杂的矩阵运算（Q 乘以 K 得到权重，再乘以 V），模型能够理解上下文的语境和词与词之间的关系。

简单来说：

每个 token 会生成三组向量：Q (Query：我想找什么)、K (Key：我有什么线索)、V (Value：我的内容是什么)
通过计算 Q 和所有 K 的相似度，得到 “该关注谁” 的权重（softmax 归一化），再对 V 做加权求和，得到 “结合上下文后的新表示”。
Multi-head 就是并行做多组注意力，让模型能同时学到多种关系（语法、指代、主题等）

这个阶段是计算量最大的部分。为了加速，推理过程中会将计算过的 K 和 V 矩阵缓存起来（即 KV Cache），避免对之前的 Token 重复计算

Output (输出层)

这是最终生成结果的一步。

经过 Transformer 层层处理后，最后得到一个新的 Embedding。输出层会将其转化为概率分布，预测下一个最可能出现的 Token。

LLM 是 “自回归” 的，这意味着它每次只生成一个 Token。生成的这个新 Token 会被加回到输入的末尾，整个流程（Tokenizer -> … -> Output）再次循环，直到生成结束符（如）或达到长度限制

实现原理

了解了之前这些背景知道，我们就可以解释 Cached Token 的技术原理了。

在 LLM（大语言模型）推理过程中，Cached Token 指的是对 KV Cache (Key-Value Cache) 的复用技术。

Transformer 架构是自回归的。在生成回答（Decode 阶段）之前，模型必须先 “理解” 输入（Prefill 阶段）。这个 “理解” 过程涉及大量的矩阵运算，计算出每个 Token 的 Key 和 Value 向量（即注意力机制的中间状态）。对于长文本（如 RAG 场景中的大量文档），每次请求都重新计算这些 KV 向量是巨大的算力浪费，这就是 Cached Token 解决的问题。

实现机制：

存储状态：当模型第一次处理前缀（Prefix，例如 System Prompt 或长文档）时，将计算好的 KV 向量驻留在 GPU 显存（VRAM）或层级存储中。
前缀匹配：当新的请求进来，如果开头部分（Prefix）与缓存中的 Token 完全一致，推理引擎（如 vLLM, SGLang）会直接加载已计算好的 KV 状态，跳过 Transformer 的前向计算过程。
PagedAttention：现代推理引擎（如 vLLM）使用类似操作系统内存分页的技术（PagedAttention）来管理这些缓存块，解决了显存碎片化问题，允许多个请求共享同一份物理显存中的 Prompt 数据

想省钱，要这样用

要在应用里稳定吃到 cached tokens（prompt caching），核心就三句话：

提示词要够长（通常 ≥ 1024 tokens 才会开始命中）
前缀要 “完全一致”（缓存按 “最长相同前缀” 命中，哪怕一个字符 / 空格不同都可能全失效）
把不变的放前面，把变化的放后面（指令/工具/示例/长背景固定；用户问题、检索结果、时间戳等放末尾）

所以我们要从设计上进行些调整才能够 “省钱”：

设计 “可缓存的前缀结构”，把 prompt 拆成两段（非常重要）：
可缓存前缀（Static Prefix）：system 指令、角色设定、规范、few-shot 示例、工具定义、长期不变的背景资料
动态尾部（Dynamic Tail）：用户输入、RAG 检索内容、实时数据、时间戳、request_id、实验开关等
多轮对话 / Agent 的注意事项
消息数组要 “只追加，不改历史”：如果你为了省 tokens 把历史消息重排、压缩、或插入到中间，很可能导致前缀变了 → cache miss。
工具定义（tools）必须完全一致，顺序也要一致，否则工具部分也进不了缓存前缀

“

OpenAI Cookbook 直接建议：静态内容放开头，可变内容放结尾；工具 / 图片也一样。

常见 “踩坑清单”

把时间戳 / 随机 ID 放在 system 开头：每次都变，等于主动让缓存失效。
JSON 序列化不稳定：同一份 tool schema 如果字段顺序、空格、换行变化，token 序列可能变 → miss（所以建议对 system/tools 做 “规范化输出”，并保持完全一致）
指令在每次请求里微调一两个字：看似小改动，可能让前 1024 tokens 出现差异，直接从 “高命中” 变成 “全 miss”。Azure 文档明确说 “前 1024 tokens 一个字符差异就会 miss”

缓存能活多久 / 怎么保持

不同厂商策略不同，但你可以这么理解：缓存不是永久的，要么靠短时间内重复使用，要么使用更长的保留策略（如果提供）。

Azure OpenAI：缓存通常在空闲 5–10 分钟清理，并且最晚 1 小时内会移除；还支持 prompt_cache_key 帮你影响路由提高命中，但同一前缀 + key 如果请求过猛（文档提到约 15 RPM 量级）可能溢出导致命中变差。
OpenAI：提供 prompt_cache_retention（默认 in_memory，也可选 24h 做更长保留），并说明缓存的是 attention prefill 产生的 KV tensors，原始提示文本不以同样方式持久化。
Anthropic Claude：通过在特定内容块上标注 cache_control 来启用 / 控制缓存（用法是显式的）。

落地建议

给开发：

把系统提示词拆成 STATIC_SYSTEM_PROMPT（长期不变）+ DYNAMIC_CONTEXT（每次变）
所有请求都按固定模板拼：STATIC_SYSTEM_PROMPT + tools + (可选固定示例) + DYNAMIC_CONTEXT + user_question
总结来说：把静态内容（System Prompt、Tools）置顶，动态内容（User Query、Time）置底；确保 JSON 序列化顺序固定；针对 Claude 需手动加标记；监控 “缓存命中率”（Cache Hit Rate）指标，确保不是在做负优化。

给产品：

缓存能让长文档分析、多轮对话变得极快且便宜。设计功能时，尽量让用户基于一个 “固定的背景”（如上传一份文档后针对该文档多次提问），这最能利用缓存优势。

实际应用场景

多轮对话 (Chatbot)：用户和 AI 聊了 20 轮，第 21 轮时，前 20 轮的历史记录就是 “Cached Token”。不用每次都重算历史记录，响应更快。
文档问答 (RAG)：上传一本 PDF 法律合同。只要文件没变，第二个问题开始，AI 就不需要重新处理这份文件
代码助手 (Coding Agent)：将整个项目的代码库结构作为 Prompt 发送给 AI。这部分内容巨大且变动不频繁，非常适合缓存。
角色扮演 / Agent：复杂的 System Prompt（设定 AI 的性格、规则、工具定义）通常很长且固定，缓存后每次调用都极快

快速安装 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系统效果难评？2025年必备的RAG评估框架与工具详解

Mon, 07 Apr 2025 02:48:18 +0000

前言：RAG崛起，评估成关键

检索增强生成（Retrieval-Augmented Generation, RAG）已成为当前大型语言模型（LLM）应用开发的主流范式。通过结合外部知识库的检索能力与 LLM 的强大生成能力，RAG 有效缓解了 LLM 的“幻觉”问题，提高了回答的事实性和时效性，在智能客服、企业知识库问答、内容生成等场景中大放异彩。

然而，RAG 系统的成功并非唾手可得。其独特的“检索+生成”两阶段流程，带来了独特的评估挑战。我们不仅要关心最终答案“看起来好不好”，更要深入探究：检索到的信息准确吗？相关吗？全面吗？生成的答案是否忠实于检索到的信息？ 简单套用通用 LLM 的评估方法往往捉襟见肘。

因此，对 RAG 系统进行精准、高效、多维度的评估，成为优化系统性能、确保应用可靠性的重中之重。幸运的是，社区和业界已经涌现出一批强大的 RAG 评估工具和框架。

本文将聚焦 RAG 评估这一核心议题，深入解析 RAG 评估的独特挑战与关键指标，并详细介绍 2025 年值得关注的主流及新兴 RAG 评估工具，助你为自己的 RAG 应用找到最趁手的“度量衡”。

一、 RAG评估的独特挑战与核心指标

评估 RAG 系统，本质上是评估两个核心组件及其协作的效果：

检索器 (Retriever): 负责根据用户问题从知识库中召回相关信息片段（上下文）。
生成器 (Generator): 即 LLM，负责基于用户问题和检索到的上下文生成最终答案。

独特挑战

双重故障点： 最终答案不好，可能是检索出错（没找到、找错了、信息不全），也可能是生成出错（没理解上下文、产生幻觉、表达不清），或者是两者协作不畅。评估需要能够诊断问题来源。
上下文依赖性： 生成质量高度依赖于检索到的上下文质量，评估需要衡量答案对上下文的“忠实度”。
指标设计的复杂性： 需要同时覆盖检索质量和生成质量的指标。

核心 RAG 评估指标

为了应对挑战，社区发展出一系列针对 RAG 的关键指标，其中许多指标巧妙地利用了更强大的 LLM（如 GPT-4）作为“裁判”来进行自动化评估：

上下文相关性 (Context Relevance/Precision): 评估检索到的上下文与用户问题的相关程度。低相关性意味着检索器引入了噪声。
上下文召回率 (Context Recall): 衡量检索到的上下文是否包含了生成“真实答案”所需的全部信息。低召回率意味着检索器遗漏了关键信息。
答案忠实度 / 接地性 (Answer Faithfulness / Groundedness): 这是 RAG 评估中最关键的指标之一。衡量生成的答案是否完全基于检索到的上下文，没有捏造信息（幻觉）。
答案相关性 (Answer Relevance): 评估生成的答案是否直接回应了用户的问题，没有跑题。

除了上述核心指标，根据具体应用，还可能关注答案的正确性（与标准答案对比）、简洁性、无害性等。

二、主流RAG评估工具深度解析 (2025年精选)

面对 RAG 的评估需求，以下工具和框架提供了强大的支持：

1. RAGAS (RAG Assessment)

https://github.com/explodinggradients/ragas

定位：RAG 评估领域的领导者和事实标准。

核心优势：

专为 RAG 设计： 提供上述所有核心 RAG 指标（Context Precision/Recall, Faithfulness, Answer Relevance）的成熟实现。
LLM 辅助评估： 大量利用 LLM 作为裁判，减少对人工标注数据的依赖。
易用性： API 简洁，易于集成。

评价：如果你正在做 RAG，RAGAS 几乎是必选的基础评估工具，用于快速衡量 RAG 流水线的整体表现。

 1from ragas import evaluate
 2from datasets import Dataset
 3import os
 4
 5os.environ["OPENAI_API_KEY"] = "your-openai-key"
 6
 7# prepare your huggingface dataset in the format
 8# Dataset({
 9# features: ['question', 'contexts', 'answer', 'ground_truths'],
10# num_rows: 25
11# })
12
13dataset: Dataset
14
15results = evaluate(dataset)

2. DeepEval

https://github.com/confident-ai/deepeval

定位：将 LLM/RAG 评估融入单元测试的框架。

RAG 相关优势:

丰富的 RAG 指标： 提供包括幻觉检测、忠实度、上下文相关性在内的超过 14 种指标，覆盖 RAG 评估关键点。
测试驱动： 与 pytest 深度集成，可以用写测试用例的方式定义和执行 RAG 评估，非常适合 CI/CD。
合成数据生成： 内置功能可辅助生成 RAG 评估所需的测试数据。

评价：对于希望将 RAG 评估工程化、自动化的团队，DeepEval 是极佳选择。它让 RAG 的质量保证更像传统软件开发。

 1from deepeval import assert_test
 2from deepeval.metrics import HallucinationMetric
 3from deepeval.test_case import LLMTestCase
 4
 5test_case = LLMTestCase(
 6 input="How many evaluation metrics does DeepEval offers?",
 7 actual_output="14+ evaluation metrics",
 8 context=["DeepEval offers 14+ evaluation metrics"]
 9)
10metric = HallucinationMetric(minimum_score=0.7)
11
12def test_hallucination():
13 assert_test(test_case, [metric])

3. TruLens

https://github.com/truera/trulens/

定位：RAG 应用的 深度可观测性与诊断 工具。

RAG 相关优势:

追踪 RAG 链路： 能详细记录 RAG 应用中从问题输入、检索执行、上下文获取到最终生成的全过程。
“Triad”评估模型： 强调输入、输出、上下文三者关系，精确评估 Context Relevance, Groundedness, Answer Relevance。
根本原因分析： 通过追踪数据，帮助开发者定位 RAG 性能瓶颈（到底是检索问题还是生成问题）。

评价：当你需要 深入理解 RAG 系统内部运作机制、进行细粒度调试时，TruLens 无可替代。它超越了简单的分数评估，提供诊断能力。

4. LLM-RAG-Eval

https://github.com/sujitpal/llm-rag-eval

定位：受 RAGAS 和 ARES 论文启发的纯 RAG 评估框架。

核心优势：

专注 RAG： 目标明确，就是提供一套全面的 RAG 流水线评估方案。
社区驱动： 作为 RAGAS 之外的新兴选择，可能融合更新的研究思路。

评价：对于希望探索 RAGAS 之外、同样专注于 RAG 评估的开源工具的团队，值得关注和尝试。

5. RAGChecker

https://github.com/amazon-science/RAGChecker

定位：提供 精细化诊断指标 的 RAG 评估框架。核心优势：

诊断性强： 提供一系列指标分别评估检索和生成模块。
高人类相关性： 其开发者声称通过元评估验证了其指标与人工判断的高度一致性，这非常有吸引力。

评价：如果你不仅想知道 RAG 系统好不好，还想知道为什么不好，并且希望自动化指标尽可能接近人类判断，RAGChecker 是一个重要的考察对象。

6. MLflow LLM Evaluate

https://github.com/mlflow/mlflow

定位：MLflow 生态系统内的 RAG 评估方案。

RAG 相关优势：

生态集成： 对于已使用 MLflow 进行实验跟踪的团队，可以无缝加入 RAG 评估。
模块化： 支持 RAG 等常见 LLM 任务的评估。

评价：主要价值在于其与 MLflow 的集成性，适合希望在现有 MLOps 流程中统一管理 RAG 评估的团队。

7. Arize AI Phoenix

https://github.com/Arize-ai/phoenix

定位：开发阶段的 LLM/RAG 可观测性与评估工具 (开源)。

RAG 相关优势：

本地优先： 方便在本地开发环境追踪、记录和分析 LLM/RAG 交互。
调试友好： 提供日志、监控和评估能力，辅助 RAG 应用的早期调试和迭代。

评价：非常适合在开发流程早期就引入观测和评估，帮助开发者快速发现和修复 RAG 问题。

补充：LangSmith

虽然 LangSmith 是一个更广泛的 LLM 开发平台，但其强大的端到端追踪能力对于理解复杂的 RAG 调用链非常有价值，可以记录检索步骤、LLM 调用细节等，是进行 RAG 调试和问题定位的重要辅助工具，常与其他 RAG 评估指标工具结合使用。

三、如何选择与组合RAG评估工具？

选择 RAG 评估工具时，请考虑：

评估目标： 是快速获得整体性能分数（RAGAS），还是需要深度诊断（TruLens, RAGChecker），或是融入自动化测试（DeepEval）？
核心指标需求： 你最关心哪些指标？（如 Faithfulness, Context Recall 等）不同工具对指标的实现和侧重可能不同。
现有技术栈： 是否已使用 Pytest (DeepEval)? 是否已使用 MLflow (MLflow LLM Evaluate)? 是否需要 LangSmith 的追踪能力？
开发阶段： 是在早期开发调试（Phoenix），还是在测试和部署阶段（RAGAS, DeepEval）？
指标与人类判断的一致性： 如果对此要求很高，RAGChecker 值得关注。

RAG 评估工具组合策略

单一工具往往不够，组合使用效果更佳：

基础组合： RAGAS (获取核心 RAG 指标) + LangSmith (追踪 RAG 链路细节)。
测试驱动组合： DeepEval (将 RAG 核心指标纳入 CI/CD) + RAGAS (作为补充或对比)。
深度诊断组合： TruLens (深入分析内部机制) + RAGAS (量化评估结果) + (可选) RAGChecker (获取高人类相关性诊断指标)。
开发期组合： Arize AI Phoenix (本地观测与初步评估) + (后续) RAGAS/DeepEval (系统性评估)。
MLflow 生态组合： MLflow LLM Evaluate + (可选) RAGAS 或 TruLens 进行更专门的 RAG 分析。

四、 RAG评估的未来展望

RAG 评估领域仍在快速发展，未来值得期待的方向包括：

更智能的 RAG 指标： 开发能更好理解上下文细微差别、更抗干扰的自动化指标。
复杂 RAG 策略评估： 针对多轮检索、迭代优化、自查询等高级 RAG 架构的评估方法。
端到端与组件级评估的结合： 既能评估整体效果，又能自动诊断是检索器还是生成器的问题。
标准化 RAG 基准： 出现更权威、更全面的 RAG 评估数据集和排行榜。
评估与优化的闭环： 评估结果能更直接地用于指导 RAG 系统（如 Prompt、检索策略、模型微调）的自动优化。

最后

RAG 为我们利用 LLM 提供了强大的范式，但其效能的发挥离不开精准的评估。从 RAGAS 的开创性工作，到 DeepEval 的工程化实践，再到 TruLens 的深度洞察，以及 LLM-RAG-Eval、RAGChecker 等新兴力量，我们拥有了前所未有的工具来度量和优化 RAG 系统。

理解 RAG 评估的独特性，掌握核心指标，并根据自身需求选择、组合合适的工具，是每一位 RAG 应用开发者走向成功的必经之路。希望这篇聚焦 RAG 评估的指南能为你披荆斩棘，提供有力的支持。

RAG 实践- Ollama+RagFlow 部署本地知识库

Tue, 18 Jun 2024 15:15:04 +0000

前言

上一篇文章我们介绍了如何利用 Ollama+AnythingLLM 来实践 RAG ，在本地部署一个知识库。借助大模型和 RAG 技术让我可以与本地私有的知识库文件实现自然语言的交互。

本文我们介绍另一种实现方式：利用 Ollama+RagFlow 来实现，其中 Ollama 中使用的模型仍然是Qwen2

我们再来回顾一下 RAG 常见的应用架构

RagFlow的安装和部署

前置条件

CPU >= 4 核
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0 & Docker Compose >= v2.26.1

安装

克隆仓库

$ git clone https://github.com/infiniflow/ragflow.git

进入 docker 文件夹，利用提前编译好的 Docker 镜像启动服务器：

$ cd ragflow/docker $ chmod +x ./entrypoint.sh $ docker compose -f docker-compose-CN.yml up -d

这一步注意docker 下载的镜像比较大，要留有足够的存储空间，我这边观察下载了约 10 个 G 左右。

服务器启动成功后再次确认服务器状态:

$ docker logs -f ragflow-server

这里注意，安装完成后并不是要进入下面两个地址

http://127.0.0.1:9380
http://172.18.0.6:9380

而是要进入：http://localhost:80 先注册账号，是下面这个页面

注册登录

在上图的界面中注册，然后登录就来到下面这个页面了

配置 Ollama 连接大模型

如下图我们先配置模型，点击右上角头像，再点击模型提供商

这里我是想连接我本地已经安装部署好的 Ollama ，通过 Ollama 我安装了 Qwen2 大模型，具体的安装步骤在之前的那篇文章里，有需要的可以移步到那里看。

打开Ollama 后，我是通过服务器模式启动的大模型

ollama serve

当然你也可以选择其他平台和其他模型，需要提供 API key，API key 的获取就去你所选模型的网站，现在有很多模型的 API 是有免费额度的。

接着我们在 RagFlow 中配置模型，注意由于 RagFlow 我是在 docker 中安装的，所以请求本地部署的 Ollama 地址要用：http://host.docker.internal:11434

创建知识库

接下来我们就可以创建知识库了

注意这里的文件类型没有 markdown,但我实测 markdown 是可以的。其他的选项，根据你的情况自行设置就好，很简单。

接下来就是上传你的文件了，也比较简单，但我发现上传后文件处理的比较慢，应该是我电脑配置的原因

文件上传并处理完成后，可以通过检索测试看一下文件有没有被正确检索。

至此，如果你上传完成全部的文件，知识库就算创建完毕了。

聊天

接着就到了展示成果的时候了，我们可以根据自己的知识库与模型进行自然语言交互了。

首先注意，在聊天配置中要把 token 设置的大一些，不然回复的内容会很少！我这里把它拉到最大值了。

展示一下成果：

我觉得还算满意。但是由于我笔记本配置一般，也没有显卡支持，所以跑的很慢，真的很慢。但如果部署在有 GPU 的服务器上，企业私有化部署供内部使用，应该会比较快的。

思考

我这里的例子是用个人笔记本电脑上的资料做的个人知识库，对于文档的提问，无论是围绕着摘要总结来做，还是围绕着全文检索，答案看起来还行，也基本能用。但是这是面向个人的或者说面向 C 端，如果面向 B 端面向企业单靠向量检索就力不从心了，一来无法对精确信息召回，二来无法与企业内部信息系统集成（大量结构化数据）。所以必须在检索阶段引入多路召回和重排序，保证数据查询的准确度。

企业内部的数据包含各种格式，更复杂的还包含各类图表等，如果在没有理解这些语义的基础之上直接提供 RAG 方案，例如简单的根据文字空白就来切分段落，就会导致语义丢失从而让最终查询的结果也是混乱不堪。

如果解决这个问题呢，除了之前说的多路召回（多跳）和重排序这种方案，目前业界还有其他思路，比如 infiniFlow提出的 Infinity AI原生数据库（https://github.com/infiniflow/infinity）

从上图可以看到，AI原生数据库不仅涵盖非结构化的内容如文档和图片，也包括结构化的信息系统。对这些信息进行有效整合，并在此基础上实现多路召回机制和最终的融合排序解决方案。

此外，很多AI 产品的上下文现在是越来越长，可能有人会说现在上下文都这么长了，还用得着 RAG 吗？我认为，RAG在知识库问答场景依然是非常必要的。LLM 的长上下文能力，对于 RAG 来说应该是很大的促进。用 OpenAI 联创 Andrej Karpathy 的一张图做个类比，他把 LLM 比喻为一台计算机的 CPU，把上下文类比为计算机的内存，那么以向量为代表的数据库，就可以看作是这台计算机的硬盘

显然你不可能买一台只有内存的电脑。内存可以很大，但也意味着很贵，并且短时间内替代不了硬盘的作用。

最后是准确性问题，关于这个问题一般有两个方向的解决思路，一种是从 RAG 下手，比如做 Embedding 模型的微调。一种是从 LLM 下手，做 LLM 微调。虽然两种我都没真正做过，但从研读的资料上得知RAG系统在实时性和成本方面相较于LLM微调具有优势，因此更受青睐。这点跟我的直觉一致。

参考

为什么 ~ 代表 macOS 和 Linux 上的主文件夹？

Fri, 20 Oct 2023 15:33:26 +0000

无论你是在 Windows 10 上安装了 Linux 子系统还是开始使用 Linux 终端，您都需要学习各种命令简写方式… 但没有一种是直观的。

例如，波浪号

~

它代表你的主文件夹

比如你想切换到当前用户主目录中的 Documents 文件夹，就这样可以：

cd ~/Documents

不用输入当前用户主目录的路径+Documents，比如：

/Users/xiaobox/Documents

当然，这是一个方便的快捷方式，但为什么要使用这个特定字符呢？

不管你相信与否，这是因为 20 世纪 70 年代的键盘。

这是 Lear Siegler ADM-3A 终端，于 1975 年首次发货。

这是一个“哑终端”，意味着它本身不是计算机，而是允许你向计算机输入命令并显示计算机中的数据。ADM-3A 的售价仅为 995 美元，无论你相信与否，这在当时都是一个不错的价格，这意味着机构可以购买多个此类终端来连接到一台中央计算机。直到今天，现代的“终端模拟器”（例如 Linux 和 macOS 中使用的终端模拟器）仍在模仿此类系统的功能。

这是一个具有巨大影响力的硬件；许多早期的软件开发都发生在它上面，这意味着键盘布局影响了一些设计选择。一探究竟：

注意到什么了吗？这是更清晰的图像。

看到右上角的键了吗？这就是 HOME 键，其作用类似于现代键盘上的 Home 键，在编辑文本时将光标移至左上角位置。它也是用于波浪号符号的键，这个关联就足够了。最终它代表了主文件夹。

没错：Linux 和基于 UNIX 的系统使用四十多年前的特定键盘代表 Home

这款键盘中还隐藏着其他细节。看到 H、J、K 和 L 键上的箭头了吗？按住 Control 并按这些键是在终端中移动光标的方式，这就是为什么这些相同的键用于在 vi 中移动光标。这些 vi 键盘快捷键反过来又启发了 Gmail、Twitter 甚至 Facebook 中的键盘快捷键。没错：甚至 Facebook 的键盘快捷键也受到了 1975 年首次销售的“哑终端”的启发。

一种你从未听说过的设备影响了人们在四十多年后仍在使用的软件中使用的设计决策。历史是不是很有意思？

Make Jar, Not War.

Tue, 05 Jul 2022 09:51:29 +0000

大约在 4 年前，关于 java 应用最终打成 jar 包还是 war 包的选择令我比较疑惑。

那时候更多的应用是打成 war 包的，即使我们知道可以打成 jar 包，但之前都是打成 war 包，并且好像打成 jar 包并没有什么特别明显的好处。

但当时令我困惑的是越来越多的实践正在不怎么说明理由的情况下转而打 jar 包，于是我开始思考……

war 包的理由

在某大型 OTA 企业内部，应用仍然打成 war 包, PaaS 平台会自动安装并配置好 tomcat，我知道这对于 web server 的统一配置和运维来说是有好处的。基于 war 背后的一系列 CI/CD 、DevOps 流程都一定有相应的适配，且就算 jar 包有我不知道的某些优势也不可能一夜之间在大型企业内部使用，需要平台和系统做出调整。

SpringBoot 在当时并未像现在这样流行，这并不意味着大家不用它，我的意思是相对新的项目来说，企业内部会有非常多 “老系统” 需要维护，我们不能指望一下子把这些老系统都用新的技术栈替换掉，就像你知道现在 web application 一般是前后端分离开发，但如果接手一个使用 jsp 的老家伙，你还得维护不是？

jar 的时代

时代不同了，说得好像过了几十年的样子，但其实也就几年光阴而已。不过仅仅是这几年的光阴却足以改变一些事情的面貌。

如今，云原生、微服务大行其道，大家好像已经非常适应这种开发模式，没有人纠结要不要用 SpringBoot，只会讨论使用的版本高还是低。更不用说打包的事情，很自然的会使用 jar,虽然这种看起来的 “最佳实践”，在长期开发的过程中会形成 “肌肉记忆”，但我们还是要讨论一下为什么。

方便

可运行 Jar 是打包自包含可运行应用程序的便捷方法。这样，我们可以最大限度地减少依赖关系。可以通过 Spring boot Maven 和 Gradle plugin 来管理依赖。

云原生友好

在自备容器的情况下（docker,k8s), jar 包可以直接作为一个 single application 来管理。

在过去我们使用 war 是为了让多应用共享 web server，现在是容器的天下，在容器内，一般情况只跑一个应用进程。由于只有一个进程，我们就可以轻松地管理它，比如重启（不会影响其他的应用，因为没有其他应用）。

版本控制

利用 git 等版本控制软件，可以控制程序运行所需要的一切（比如配置文件）

易于扩展

例如，将其复制到另一台服务器，然后“ just run it!” 无需安装和/或配置容器

参考

https://medium.com/@satyajit.nalavade/make-jar-not-war-josh-long-d6ce5fbb8a23

自顶向下学习 RocketMQ（三）：消息存储

Wed, 08 Dec 2021 10:34:01 +0000

前言

通过前面两篇中的应用例子，我们已经大概知道 RocketMQ 的架构是什么样的了。如图：

主要是以下几个部分：

producer
consumer
broker
nameserver

如果你自己动手部署过 RocketMQ, 相信对下面的这个部署架构图会非常清楚：

本文我们来了解一下 RockerMQ 中的消息存储是如何设计和实现的。

消息存储

前知识

在介绍之前我们先了解几个基本概念：

分区

消息队列中同一个 topic 中的消息可能会存储到多个分区上，如下图：

offset

消息在 broker 上的每个分区都是组织成一个文件列表，消费者拉取数据需要知道数据在文件中的偏移量，这个偏移量就是所谓 offset。Offset 是绝对偏移量，服务器会将 offset 转化为具体文件的相对偏移量 , 消费者消费消息队列的偏移量 , 通过 offset 找到 message

存储架构

消息存储是 RocketMQ 中最为复杂和最为重要的一部分。

上面这个图我们可以更简化一下：

RocketMQ 为 Producer 和 Consumer 分别设计了不同的存储结构，Producer 对应 CommitLog, Consumer 对应 ConsumeQueue。

这其实是“异步化“，或者说”离线计算“的一个典型例子。这里之所以可以用“异步线程”，也是因为消息队列天生就是用来“缓冲消息”的。只要消息到了 CommitLog，发送的消息也就不会丢。只要消息不丢，那就有了“充足的回旋余地”，用一个后台线程慢慢同步到 ConsumeQueue，再由 Consumer 消费。可以说，这也是在消息队列内部的一个典型的“最终一致性”的案例：Producer 发了消息，进了 CommitLog，此时 Consumer 并不可见。但没关系，只要消息不丢，消息最终肯定会进入 ConsumeQueue，让 Consumer 可见。

CommitLog

消息主体以及元数据的存储主体，存储 Producer 端写入的消息主体内容，消息内容不是定长的。

生成规则

CommitLog 单个文件大小默认 1G, 文件名长度为 20 位，左边补零，剩余为起始偏移量，比如 00000000000000000000 代表了第一个文件，起始偏移量为 0，文件大小为 1G=1073741824；当第一个文件写满了，第二个文件为 00000000001073741824，起始偏移量为 1073741824，以此类推。消息主要是顺序写入日志文件，当文件满了，写入下一个文件。

存储路径

 1❯ cd ~/store
 2
 3~/store
 4❯ ll
 5total 16
 6-rw-r--r-- 1 root staff 0B Dec 6 10:48 abort
 7-rw-r--r-- 1 root staff 4.0K Dec 6 15:46 checkpoint
 8drwxr-xr-x 3 root staff 96B Sep 7 16:30 commitlog
 9drwxr-xr-x 12 root staff 384B Dec 6 15:46 config
10drwxr-xr-x 5 root staff 160B Nov 30 14:06 consumequeue
11drwxr-xr-x 3 root staff 96B Dec 6 11:46 index
12-rw-r--r-- 1 root staff 4B Dec 6 11:46 lock

存储规则

RocketMQ 采用了单一的日志文件，即把同一台机器上面所有 topic 的消息，存放在一个文件里面，从而避免了随机的磁盘写入，提高了性能。

RocketMQ 中主要保存了 CommitLog、Consume Queue、Index File 三种数据文件。由于内存和磁盘都是有限的资源，Broker 不可能永久地保存所有数据，所以一些超过保存期限的数据会被定期删除。RocketMQ 通过设置数据过期时间来删除额外的数据文件。

什么样的文件可以被删除？

如果非当前写文件在一定时间间隔内没有再次被更新，则认为是过期文件，可以被删除。

RocketMQ 不会管这个这个文件上的消息是否被全部消费。默认每个文件的过期时间为 72 小时。

1 // The number of hours to keep a log file before deleting it (in hours)
2 @ImportantField
3 private int fileReservedTime = 72;

通过在 Broker 配置文件中设置 fileReservedTime 来改变过期时间，单位为小时

1brokerClusterName = DefaultCluster
2brokerName = broker-a
3brokerId = 0
4deleteWhen = 04
5fileReservedTime = 48
6brokerRole = ASYNC_MASTER
7flushDiskType = ASYNC_FLUSH

删除的整体流程是在 DefaultMessageStore 中启动了一个定时任务来执行的删除操作：

这个定时的周期是 10 秒，每 10 秒会执行一次，可以通过修改参数配置。

1// Resource reclaim interval
2//private int cleanResourceInterval = 10000;
3
4 this.scheduledExecutorService.scheduleAtFixedRate(new Runnable() {
5 @Override
6 public void run() {
7 DefaultMessageStore.this.cleanFilesPeriodically();
8 }
9 }, 1000 * 60, this.messageStoreConfig.getCleanResourceInterval(), TimeUnit.MILLISECONDS);

具体逻辑是这样的：

 1 private void deleteExpiredFiles() {
 2
 3 int deleteCount = 0;
 4 long fileReservedTime = DefaultMessageStore.this.getMessageStoreConfig().getFileReservedTime();
 5 int deletePhysicFilesInterval = DefaultMessageStore.this.getMessageStoreConfig().getDeleteCommitLogFilesInterval();
 6 int destroyMapedFileIntervalForcibly = DefaultMessageStore.this.getMessageStoreConfig().getDestroyMapedFileIntervalForcibly();
 7
 8 boolean timeup = this.isTimeToDelete();
 9 boolean spacefull = this.isSpaceToDelete();
10 boolean manualDelete = this.manualDeleteFileSeveralTimes > 0;
11
12 if (timeup || spacefull || manualDelete) {
13
14 if (manualDelete)
15 this.manualDeleteFileSeveralTimes--;
16
17 boolean cleanAtOnce = DefaultMessageStore.this.getMessageStoreConfig().isCleanFileForciblyEnable() && this.cleanImmediately;
18
19 log.info("begin to delete before {} hours file. timeup: {} spacefull: {} manualDeleteFileSeveralTimes: {} cleanAtOnce: {}",
20 fileReservedTime,
21 timeup,
22 spacefull,
23 manualDeleteFileSeveralTimes,
24 cleanAtOnce);
25
26 fileReservedTime *= 60 * 60 * 1000;
27
28 deleteCount = DefaultMessageStore.this.commitLog.deleteExpiredFile(fileReservedTime, deletePhysicFilesInterval,
29 destroyMapedFileIntervalForcibly, cleanAtOnce);
30 if (deleteCount > 0) {
31 } else if (spacefull) {
32 log.warn("disk space will be full soon, but delete file failed.");
33 }
34 }
35}

可以看到，当满足以下三个条件之一时，将执行删除操作：

当前时间等于已经配置的删除时间，默认为凌晨 4 点，开始执行删除文件操作
```
1// When to delete,default is at 4 am
2 @ImportantField
3 private String deleteWhen = "04";
```

磁盘使用空间超过 85%

1private final double diskSpaceCleanForciblyRatio =
2 Double.parseDouble(System.getProperty("rocketmq.broker.diskSpaceCleanForciblyRatio", "0.85"));

手动执行删除，预留，可以通过调用 excuteDeleteFilesManualy 方法手工触发过期文件删除，目前 RocketMQ 暂未封装手工触发文件删除的命令。

数据结构

从源码上直接看一下 CommitLog 存储时逻辑上的数据结构情况（代码源自 CommitLog 类）：

 1protected PutMessageResult encode(MessageExtBrokerInner msgInner) {
 2 /**
 3 * Serialize message
 4 */
 5 final byte[] propertiesData =
 6 msgInner.getPropertiesString() == null ? null : msgInner.getPropertiesString().getBytes(MessageDecoder.CHARSET_UTF8);
 7
 8 final int propertiesLength = propertiesData == null ? 0 : propertiesData.length;
 9
10 if (propertiesLength > Short.MAX_VALUE) {
11 log.warn("putMessage message properties length too long. length={}", propertiesData.length);
12 return new PutMessageResult(PutMessageStatus.PROPERTIES_SIZE_EXCEEDED, null);
13 }
14
15 final byte[] topicData = msgInner.getTopic().getBytes(MessageDecoder.CHARSET_UTF8);
16 final int topicLength = topicData.length;
17
18 final int bodyLength = msgInner.getBody() == null ? 0 : msgInner.getBody().length;
19
20 final int msgLen = calMsgLength(msgInner.getSysFlag(), bodyLength, topicLength, propertiesLength);
21
22 // Exceeds the maximum message
23 if (msgLen > this.maxMessageSize) {
24 CommitLog.log.warn("message size exceeded, msg total size: " + msgLen + ", msg body size: " + bodyLength
25 + ", maxMessageSize: " + this.maxMessageSize);
26 return new PutMessageResult(PutMessageStatus.MESSAGE_ILLEGAL, null);
27 }
28
29 // Initialization of storage space
30 this.resetByteBuffer(encoderBuffer, msgLen);
31 // 1 TOTALSIZE
32 this.encoderBuffer.putInt(msgLen);
33 // 2 MAGICCODE
34 this.encoderBuffer.putInt(CommitLog.MESSAGE_MAGIC_CODE);
35 // 3 BODYCRC
36 this.encoderBuffer.putInt(msgInner.getBodyCRC());
37 // 4 QUEUEID
38 this.encoderBuffer.putInt(msgInner.getQueueId());
39 // 5 FLAG
40 this.encoderBuffer.putInt(msgInner.getFlag());
41 // 6 QUEUEOFFSET, need update later
42 this.encoderBuffer.putLong(0);
43 // 7 PHYSICALOFFSET, need update later
44 this.encoderBuffer.putLong(0);
45 // 8 SYSFLAG
46 this.encoderBuffer.putInt(msgInner.getSysFlag());
47 // 9 BORNTIMESTAMP
48 this.encoderBuffer.putLong(msgInner.getBornTimestamp());
49 // 10 BORNHOST
50 socketAddress2ByteBuffer(msgInner.getBornHost() ,this.encoderBuffer);
51 // 11 STORETIMESTAMP
52 this.encoderBuffer.putLong(msgInner.getStoreTimestamp());
53 // 12 STOREHOSTADDRESS
54 socketAddress2ByteBuffer(msgInner.getStoreHost() ,this.encoderBuffer);
55 // 13 RECONSUMETIMES
56 this.encoderBuffer.putInt(msgInner.getReconsumeTimes());
57 // 14 Prepared Transaction Offset
58 this.encoderBuffer.putLong(msgInner.getPreparedTransactionOffset());
59 // 15 BODY
60 this.encoderBuffer.putInt(bodyLength);
61 if (bodyLength > 0)
62 this.encoderBuffer.put(msgInner.getBody());
63 // 16 TOPIC
64 this.encoderBuffer.put((byte) topicLength);
65 this.encoderBuffer.put(topicData);
66 // 17 PROPERTIES
67 this.encoderBuffer.putShort((short) propertiesLength);
68 if (propertiesLength > 0)
69 this.encoderBuffer.put(propertiesData);
70
71 encoderBuffer.flip();
72 return null;
73}

结合上表，一条消息的存储内容如下：

将所有的消息存储在一起就是 CommitLog 的全部内容，如下：

注意以上图中所画为抽象结构，具体实现上 commitLog 内部还有

MappedFile
MappedFileQueue

 1public class CommitLog {
 2 // Message's MAGIC CODE daa320a7
 3 public final static int MESSAGE_MAGIC_CODE = -626843481;
 4 protected static final InternalLogger log = InternalLoggerFactory.getLogger(LoggerName.STORE_LOGGER_NAME);
 5 // End of file empty MAGIC CODE cbd43194
 6 protected final static int BLANK_MAGIC_CODE = -875286124;
 7 protected final MappedFileQueue mappedFileQueue;
 8 protected final DefaultMessageStore defaultMessageStore;
 9 
10
11public class MappedFileQueue {
12 private static final InternalLogger log = InternalLoggerFactory.getLogger(LoggerName.STORE_LOGGER_NAME);
13 private static final InternalLogger LOG_ERROR = InternalLoggerFactory.getLogger(LoggerName.STORE_ERROR_LOGGER_NAME);
14
15 private static final int DELETE_FILES_BATCH_MAX = 10;
16
17 private final String storePath;
18
19 protected final int mappedFileSize;
20
21 protected final CopyOnWriteArrayList<MappedFile> mappedFiles = new CopyOnWriteArrayList<MappedFile>();

CommitLog MappedFileQueue MappedFile 三者的关系如下：

MappedFile 和物理文件是一一对应的。

这一点我们可以从 MappedFileQueue 的 load 方法中看出：

 1public boolean load() {
 2
 3 File dir = new File(this.storePath);
 4 File[] ls = dir.listFiles();
 5 if (ls != null) {
 6 return doLoad(Arrays.asList(ls));
 7 }
 8 return true;
 9}
10
11public boolean doLoad(List<File> files) {
12 // ascending order
13 files.sort(Comparator.comparing(File::getName));
14
15 for (File file : files) {
16 if (file.length() != this.mappedFileSize) {
17 log.warn(file + "\t" + file.length()
18 + " length not matched message store config value, ignore it");
19 return true;
20 }
21
22 try {
23 MappedFile mappedFile = new MappedFile(file.getPath(), mappedFileSize);
24
25 mappedFile.setWrotePosition(this.mappedFileSize);
26 mappedFile.setFlushedPosition(this.mappedFileSize);
27 mappedFile.setCommittedPosition(this.mappedFileSize);
28 this.mappedFiles.add(mappedFile);
29 log.info("load " + file.getPath() + " OK");
30 } catch (IOException e) {
31 log.error("load file " + file + " error", e);
32 return false;
33 }
34 }
35 return true;
36}

ConsumeQueue

上文我们讲了 RocketMQ 将所有 topic 的消息都存储在 CommitLog 中，由于是顺序写所以性能比较好，那么随之而来的问题就是查询或者说读取消息的时候怎么办？用这个结构存储效率高，但如果用这个结构读取消息看起来不方便，那 RocketMQ 是怎么做的呢？

如果你本地有 commitLog 文件，可以直接读取一下看看数据：

 1 public static ByteBuffer read(String path) throws Exception {
 2 File file = new File(path);
 3 FileInputStream fin = new FileInputStream(file);
 4 byte[] bytes = new byte[(int) file.length()];
 5 fin.read(bytes);
 6 ByteBuffer buffer = ByteBuffer.wrap(bytes);
 7 return buffer;
 8 }
 9
10 public static void main(String[] args) throws Exception {
11 String filePath = "/Users/xiaohezi/store/commitlog/00000000000000000000";
12 ByteBuffer buffer = read(filePath);
13 List<MessageExt> messageList = new ArrayList<>();
14 while (true) {
15 MessageExt decodeMsgs = MessageDecoder.decode(buffer);
16 if (decodeMsgs == null) {
17 break;
18 }
19 messageList.add(decodeMsgs);
20 }
21 for (MessageExt ms : messageList) {
22 System.out.println("主题：" + ms.getTopic() + " 消息：" +
23 new String(ms.getBody()) + "队列 ID:" + ms.getQueueId() + " 存储地址：" + ms.getStoreHost());
24 }
25 }

程序执行的效率其实并不低，那么 RocketMQ 是怎样进行高效的检索消息的呢？

为了说清楚这个问题，我们先来看个基本概念

MessageQueue

先来个图直观地感受一下：

所谓 MessageQueue 虽然直译是“消息队列”，但它和我们所理解的 “分片”、“分区” 是一回事儿。以后提到 RocketMQ 的分区、分片、队列其实都是对应 messageQueue。

比如我们的 Topic 里面有 100 条数据，该 Topic 默认是 4 个队列，那么每个队列中大约 25 条数据。然后，这些 MessageQueue 是和 Broker 绑定在一起的，就是说每个 MessageQueue 都可能处于不同的 Broker 机器上，这取决于你的队列数量和 Broker 集群。

既然 MessageQueue 是多个，那么在消息发送的时候，势必要通过某种方式选择一个队列。默认的情况下，就是通过轮询来获取一个消息队列。

在消息发送时候的应用如下面引用的官方文档所述：

“

Producer 端在发送消息的时候，会先根据 Topic 找到指定的 TopicPublishInfo，在获取了 TopicPublishInfo 路由信息后，RocketMQ 的客户端在默认方式下 selectOneMessageQueue() 方法会从 TopicPublishInfo 中的 messageQueueList 中选择一个队列（MessageQueue）进行发送消息。具体的容错策略均在 MQFaultStrategy 这个类中定义。这里有一个 sendLatencyFaultEnable 开关变量，如果开启，在随机递增取模的基础上，再过滤掉 not available 的 Broker 代理。所谓的"latencyFaultTolerance" ，是指对之前失败的，按一定的时间做退避。例如，如果上次请求的 latency 超过 550Lms，就退避 3000Lms；超过 1000L，就退避 60000L；如果关闭，采用随机递增取模的方式选择一个队列（MessageQueue）来发送消息，latencyFaultTolerance 机制是实现消息发送高可用的核心关键所在。

”

1public MessageQueue selectOneMessageQueue() {
2 int index = this.sendWhichQueue.incrementAndGet();
3 int pos = Math.abs(index) % this.messageQueueList.size();
4 if (pos < 0)
5 pos = 0;
6 return this.messageQueueList.get(pos);
7}

consumeQueue

接着我们来看下本节的重点 consumeQueue，先看下它的文件组织结构：

其中 队列 ID，就是以 MessageQueue 队列 ID 命名的。

每个 cosumequeue 文件的名称 fileName，名字长度为 20 位，左边补零，剩余为起始偏移量；比如 00000000000000000000 代表了第一个文件，起始偏移量为 0，文件大小为 600W，当第一个文件满之后创建的第二个文件的名字为 00000000000006000000，起始偏移量为 6000000，以此类推，第三个文件名字为 00000000000012000000，起始偏移量为 12000000，消息存储的时候会顺序写入文件，当文件满了，写入下一个文件。

RocketMQ 的 ConsumeQueue 中不存储具体的消息，具体的消息由 CommitLog 存储，ConsumeQueue 中只存储路由到该 queue 中的消息在 CommitLog 中的 offset，消息的大小以及消息所属的 tag 的 hash（tagCode），一共只占 20 个字节：

我们可以按照这个格式输出一下 ConsumerQueue 文件的内容：

 1 public static void main(String[] args) throws Exception {
 2
 3 String path = "/Users/root/store/consumequeue/TopicTest/0/00000000000000000000";
 4 ByteBuffer buffer = read(path);
 5 while (true){
 6 long offset = buffer.getLong();
 7 long size = buffer.getInt();
 8 long code = buffer.getLong();
 9 if (size==0){
10 break;
11 }
12 System.out.println("消息长度："+size+" 消息偏移量：" +offset+" tag hashcode:"+code);
13 }
14 System.out.println("--------------------------");
15
16}
17
18消息长度：201 消息偏移量：201 tag hashcode:2598919
19消息长度：201 消息偏移量：1005 tag hashcode:2598919
20消息长度：201 消息偏移量：1809 tag hashcode:2598919
21...

上面输出的结果中，消息偏移量的差值等于 = 消息长度 * 队列长度，具体到本例就是

804(1005-201) = 201 * 4（从 0-3 共 4 个队列）

为什么是这样？因为每个队列的初始偏移量不同，我以我本地 4 个队列（0-3），每个队列只有一个文件（00000000000000000000）为例，则每个文件的初始 offset 为：

队列 0 偏移量 201
队列 1 偏移量 402
队列 2 偏移量 603
队列 3 偏移量 0

当读取一条消息时，会先读 ConsumeQueue，再读 CommitLog。怎么知道消息存储在哪个 CommitLog 文件上？看一下以下两段代码，出自 CommitLog 和 MappedFileQueue 2 个类：

 1 public SelectMappedBufferResult getData(final long offset, final boolean returnFirstOnNotFound) {
 2 int mappedFileSize = this.defaultMessageStore.getMessageStoreConfig().getMappedFileSizeCommitLog();
 3 MappedFile mappedFile = this.mappedFileQueue.findMappedFileByOffset(offset, returnFirstOnNotFound);
 4 if (mappedFile != null) {
 5 int pos = (int) (offset % mappedFileSize);
 6 SelectMappedBufferResult result = mappedFile.selectMappedBuffer(pos);
 7 return result;
 8 }
 9
10 return null;
11 }
12
13/**
14 * Finds a mapped file by offset.
15 *
16 * @param offset Offset.
17 * @param returnFirstOnNotFound If the mapped file is not found, then return the first one.
18 * @return Mapped file or null (when not found and returnFirstOnNotFound is <code>false</code>).
19 */
20public MappedFile findMappedFileByOffset(final long offset, final boolean returnFirstOnNotFound) {
21 try {
22 MappedFile firstMappedFile = this.getFirstMappedFile();
23 MappedFile lastMappedFile = this.getLastMappedFile();
24 if (firstMappedFile != null && lastMappedFile != null) {
25 if (offset < firstMappedFile.getFileFromOffset() || offset >= lastMappedFile.getFileFromOffset() + this.mappedFileSize) {
26 LOG_ERROR.warn("Offset not matched. Request offset: {}, firstOffset: {}, lastOffset: {}, mappedFileSize: {}, mappedFiles count: {}",
27 offset,
28 firstMappedFile.getFileFromOffset(),
29 lastMappedFile.getFileFromOffset() + this.mappedFileSize,
30 this.mappedFileSize,
31 this.mappedFiles.size());
32 } else {
33 int index = (int) ((offset / this.mappedFileSize) - (firstMappedFile.getFileFromOffset() / this.mappedFileSize));
34 MappedFile targetFile = null;
35 try {
36 targetFile = this.mappedFiles.get(index);
37 } catch (Exception ignored) {
38 }
39
40 if (targetFile != null && offset >= targetFile.getFileFromOffset()
41 && offset < targetFile.getFileFromOffset() + this.mappedFileSize) {
42 return targetFile;
43 }
44
45 for (MappedFile tmpMappedFile : this.mappedFiles) {
46 if (offset >= tmpMappedFile.getFileFromOffset()
47 && offset < tmpMappedFile.getFileFromOffset() + this.mappedFileSize) {
48 return tmpMappedFile;
49 }
50 }
51 }
52
53 if (returnFirstOnNotFound) {
54 return firstMappedFile;
55 }
56 }
57 } catch (Exception e) {
58 log.error("findMappedFileByOffset Exception", e);
59 }
60
61 return null;
62}

假设 1073742827 为物理偏移量（物理偏移量也即全局偏移量），则其对应的相对偏移量为 1003（1003 = 1073742827 - 1073741824），并且该偏移量位于第二个 CommitLog。

根据上面的代码，当我们从 commitLog 文件列表根据 consumeQueue 提供的偏移量 offset 就可以锁定具体的 commitLog 文件，然后根据 offset 计算出 position, 可以找到对应的消息。

 1 public SelectMappedBufferResult selectMappedBuffer(int pos) {
 2 int readPosition = getReadPosition();
 3 if (pos < readPosition && pos >= 0) {
 4 if (this.hold()) {
 5 ByteBuffer byteBuffer = this.mappedByteBuffer.slice();
 6 byteBuffer.position(pos);
 7 int size = readPosition - pos;
 8 ByteBuffer byteBufferNew = byteBuffer.slice();
 9 byteBufferNew.limit(size);
10 return new SelectMappedBufferResult(this.fileFromOffset + pos, byteBufferNew, size, this);
11 }
12 }
13
14 return null;
15}

除了通过 offset 找到对应的消息，还要以通过 message ID 查找。

原理是一样的，只不过会先通过 message ID 将偏移量解析出来：

 1public static MessageId decodeMessageId(final String msgId) throws UnknownHostException {
 2 SocketAddress address;
 3 long offset;
 4 int ipLength = msgId.length() == 32 ? 4 * 2 : 16 * 2;
 5
 6 byte[] ip = UtilAll.string2bytes(msgId.substring(0, ipLength));
 7 byte[] port = UtilAll.string2bytes(msgId.substring(ipLength, ipLength + 8));
 8 ByteBuffer bb = ByteBuffer.wrap(port);
 9 int portInt = bb.getInt(0);
10 address = new InetSocketAddress(InetAddress.getByAddress(ip), portInt);
11
12 // offset
13 byte[] data = UtilAll.string2bytes(msgId.substring(ipLength + 8, ipLength + 8 + 16));
14 bb = ByteBuffer.wrap(data);
15 offset = bb.getLong(0);
16
17 return new MessageId(address, offset);
18}

consumeQueue 文件是何时创建并更新的？

ConsumeQueue 是消息消费队列文件，消息达到 commitlog 文件后将被异步转发到消息消费队列，供消息消费者消费。

RocketMQ 的具体做法是，使用 Broker 端的后台服务线程—ReputMessageService 不停地分发请求并异步构建 ConsumeQueue

indexFile

上图中有一个查询类型是通过messageKey 查询。

它是一种模型查询，查询条件是：Topic+Message Key。说起查询，阿里云有一个推荐的消息查询过程：

messagekey 是什么，它的作用又是什么呢？

顾名思义就是消息的一个标识，可以在客户端发送消息时设置，主要用来在业务上区别每条消息的不同，比如一般我们会把 订单 id、用户 id能在业务上达到区别数据的目的是值设置进去，以方便后面的查询。

 1@GetMapping("/produce")
 2public void produceMsg() {
 3
 4 Map<String, Object> headers = Maps.newHashMapWithExpectedSize(16);
 5 headers.put(MessageConst.PROPERTY_TAGS, "test02");
 6 headers.put(MessageConst.PROPERTY_KEYS,"messageKey");
 7
 8 Message message = MessageBuilder.createMessage("Hello RocketMQ!", new MessageHeaders(headers));
 9 output.send(message);
10 System.out.println("发送了消息 " + message);
11
12}

如果我们想根据 messageKey 来查询消息，RocketMQ 是怎么做的呢？

RocketMQ 引入 Hash 索引机制，为消息建立索引，像上文的 messageKey 就是根据索引查询出来的。IndexFile 是消息索引文件，主要存储的是 key 和 offset 的对应关系。

indexFile（索引文件）提供了一种可以通过 key 或时间区间来查询消息的方法。文件名 fileName 是以创建时的时间戳命名的，固定的单个 IndexFile 文件大小约为 400M，一个 IndexFile 可以保存 2000W 个索引。

RocketMQ 的索引文件逻辑结构，类似 JDK 中 HashMap 的实现。索引文件的具体结构如下：

文件由以下几部分组成：

indexHeader
500w 个 hash 槽
2000w 个 index 条目

indexHeader

IndexFile 的头部，占 40 个字节。主要包含以下字段

beginTimestamp：该 IndexFile 文件中包含消息的最小存储时间。
endTimestamp：该 IndexFile 文件中包含消息的最大存储时间。
beginPhyoffset：该 IndexFile 文件中包含消息的最小 CommitLog 文件偏移量。
endPhyoffset：该 IndexFile 文件中包含消息的最大 CommitLog 文件偏移量。
hashSlotcount：该 IndexFile 文件中包含的 hashSlot 的总数。
indexCount：该 IndexFile 文件中已使用的 Index 条目个数。

 1public class IndexHeader {
 2 public static final int INDEX_HEADER_SIZE = 40;
 3 private static int beginTimestampIndex = 0;
 4 private static int endTimestampIndex = 8;
 5 private static int beginPhyoffsetIndex = 16;
 6 private static int endPhyoffsetIndex = 24;
 7 private static int hashSlotcountIndex = 32;
 8 private static int indexCountIndex = 36;
 9 private final ByteBuffer byteBuffer;
10 private AtomicLong beginTimestamp = new AtomicLong(0);
11 private AtomicLong endTimestamp = new AtomicLong(0);
12 private AtomicLong beginPhyOffset = new AtomicLong(0);
13 private AtomicLong endPhyOffset = new AtomicLong(0);
14 private AtomicInteger hashSlotCount = new AtomicInteger(0);
15
16 private AtomicInteger indexCount = new AtomicInteger(1);

slot table

4*500W 的 Slot Table 并不保存真正的索引数据，而是保存每个槽位对应的单向链表的头

索引数据

20*2000W 是真正的索引数据，即一个 Index File 可以保存 2000W 个索引。

怎么给一条消息建议索引？

先是根据 key 计算 hashcode，对 500w 取模，就可以知道位于哪个 hash 槽。indexHead 占了文件的前面的 40 字节。然后每个 hash 槽占 4 个字节。具体在文件的位置是由公式 40 + keyIndex*4 计算得到的。
再计算 index 条目位置，一条消息 hash 槽的位置是根据 key 决定的，index 条目的位置是放入的顺序决定的，这叫顺序写。index 条目首先要跨过 indexHead 和 500w 个 hash 槽的大小。然后根据当前是第几条 index 条目，就放入到第几个位置去。计算公式是：40 个字节的 indexHead+500w 个 * 4 字节的 hash 槽大小 + 当前 index 索引的值 * 20 字节

怎么查询索引文件？

“

“按照 Message Key 查询消息”的方式，RocketMQ 的具体做法是，主要通过 Broker 端的 QueryMessageProcessor 业务处理器来查询，读取消息的过程就是用 topic 和 key 找到 IndexFile 索引文件中的一条记录，根据其中的 commitLog offset 从 CommitLog 文件中读取消息的实体内容。

”

我们发送的消息体中，包含 Message Key 或 Unique Key，那么就会给它们每一个都构建索引，索引文件根据 key 来查询消息的流程主要是：

根据查询的 key 的 hashcode%slotNum 得到具体的槽的位置 (slotNum 是一个索引文件里面包含的最大槽的数目，例如图中所示 slotNum=500w)
根据 slotValue(slot 位置对应的值）查找到索引项列表的最后一项（倒序排列，slotValue 总是指向最新的一个索引项）
遍历索引项列表返回查询时间范围内的结果集（默认一次最大返回的 32 条记录）

 1 public boolean putKey(final String key, final long phyOffset, final long storeTimestamp) {
 2 if (this.indexHeader.getIndexCount() < this.indexNum) {
 3 int keyHash = indexKeyHashMethod(key);
 4 int slotPos = keyHash % this.hashSlotNum;
 5 int absSlotPos = IndexHeader.INDEX_HEADER_SIZE + slotPos * hashSlotSize;
 6
 7 FileLock fileLock = null;
 8
 9 try {
10
11 // fileLock = this.fileChannel.lock(absSlotPos, hashSlotSize,
12 // false);
13 int slotValue = this.mappedByteBuffer.getInt(absSlotPos);
14 if (slotValue <= invalidIndex || slotValue > this.indexHeader.getIndexCount()) {
15 slotValue = invalidIndex;
16 }
17
18 long timeDiff = storeTimestamp - this.indexHeader.getBeginTimestamp();
19
20 timeDiff = timeDiff / 1000;
21
22 if (this.indexHeader.getBeginTimestamp() <= 0) {
23 timeDiff = 0;
24 } else if (timeDiff > Integer.MAX_VALUE) {
25 timeDiff = Integer.MAX_VALUE;
26 } else if (timeDiff < 0) {
27 timeDiff = 0;
28 }
29
30 int absIndexPos =
31 IndexHeader.INDEX_HEADER_SIZE + this.hashSlotNum * hashSlotSize
32 + this.indexHeader.getIndexCount() * indexSize;
33
34 this.mappedByteBuffer.putInt(absIndexPos, keyHash);
35 this.mappedByteBuffer.putLong(absIndexPos + 4, phyOffset);
36 this.mappedByteBuffer.putInt(absIndexPos + 4 + 8, (int) timeDiff);
37 this.mappedByteBuffer.putInt(absIndexPos + 4 + 8 + 4, slotValue);
38
39 this.mappedByteBuffer.putInt(absSlotPos, this.indexHeader.getIndexCount());
40
41 if (this.indexHeader.getIndexCount() <= 1) {
42 this.indexHeader.setBeginPhyOffset(phyOffset);
43 this.indexHeader.setBeginTimestamp(storeTimestamp);
44 }
45
46 if (invalidIndex == slotValue) {
47 this.indexHeader.incHashSlotCount();
48 }
49 this.indexHeader.incIndexCount();
50 this.indexHeader.setEndPhyOffset(phyOffset);
51 this.indexHeader.setEndTimestamp(storeTimestamp);
52
53 return true;
54 } catch (Exception e) {
55 log.error("putKey exception, Key: " + key + " KeyHashCode: " + key.hashCode(), e);
56 } finally {
57 if (fileLock != null) {
58 try {
59 fileLock.release();
60 } catch (IOException e) {
61 log.error("Failed to release the lock", e);
62 }
63 }
64 }
65 } else {
66 log.warn("Over index file capacity: index count = " + this.indexHeader.getIndexCount()
67 + "; index max num = " + this.indexNum);
68 }
69
70 return false;
71}

简单说就是：先是根据 key 计算 hashcode，对 500w 取模，就可以知道位于哪个 hash 槽。根据槽值的内容，再通过计算 index 条目位置，获取到 index 条目，再依次获取上一个 hash 冲突节点的 index 条目。

总结

RocketMQ 文件存储模型层次结构

RocketMQ 存储的文件主要包括 Commitlog 文件、ConsumeQueue 文件、Index 文件。

消息存储是由 ConsumeQueue 和 CommitLog 配合完成。CommitLog 存储消息真正内容的文件。他们都有各自的生成规则、存储路径、数据结构。内部还有与与他们相映射的 java 数据结构如 MappedFile、MappedByteBuffer、MappedFileQueue 等。

“

RocketMQ 采用的是混合型的存储结构，即为 Broker 单个实例下所有的队列共用一个日志数据文件（即为 CommitLog）来存储。RocketMQ 的混合型存储结构（多个 Topic 的消息实体内容都存储于一个 CommitLog 中）针对 Producer 和 Consumer 分别采用了数据和索引部分相分离的存储结构，Producer 发送消息至 Broker 端，然后 Broker 端使用同步或者异步的方式对消息刷盘持久化，保存至 CommitLog 中。只要消息被刷盘持久化至磁盘文件 CommitLog 中，那么 Producer 发送的消息就不会丢失。正因为如此，Consumer 也就肯定有机会去消费这条消息。当无法拉取到消息后，可以等下一次消息拉取，同时服务端也支持长轮询模式，如果一个消息拉取请求未拉取到消息，Broker 允许等待 30s 的时间，只要这段时间内有新消息到达，将直接返回给消费端。这里，RocketMQ 的具体做法是，使用 Broker 端的后台服务线程—ReputMessageService 不停地分发请求并异步构建 ConsumeQueue（逻辑消费队列）和 IndexFile（索引文件）数据。

”

ConsumeQueue（逻辑消费队列）作为消费消息的索引，保存了指定 Topic 下的队列消息在 CommitLog 中的起始物理偏移量 offset，消息大小 size 和消息 Tag 的 HashCode 值。而 IndexFile（索引文件）则只是为了消息查询提供了一种通过 key 或时间区间来查询消息的方法。

最后结合消息的生产、消费与存储来一起看一下这个流程：

参考

自顶向下学习 RocketMQ（一）: QuickStart

Tue, 30 Nov 2021 06:42:12 +0000

安装部署 RocketMQ

采用源码编译安装，注意请提前将 maven 安装调试好。

操作系统 macOS
RocketMQ 版本：4.9.2
Maven 版本 3.3.9
JDK 版本 1.8.0_181

以下安装是单 Master 模式，非集群模式，仅适用于本地开发和测试环境。

下载源码包

1wget https://dlcdn.apache.org/rocketmq/4.9.2/rocketmq-all-4.9.2-source-release.zip

解压源码并进行编译

1> unzip rocketmq-all-4.9.2-source-release.zip
2> cd rocketmq-all-4.9.2/
3> mvn -Prelease-all -DskipTests clean install -U
4> cd distribution/target/rocketmq-4.9.2/rocketmq-4.9.2

启动 Name Server

在上一步的目录下，执行：

 1> nohup sh bin/mqnamesrv &
 2> tail -f ~/logs/rocketmqlogs/namesrv.log
 3
 4021-11-24 16:50:14 INFO main - tls.client.keyPassword = null
 52021-11-24 16:50:14 INFO main - tls.client.certPath = null
 62021-11-24 16:50:14 INFO main - tls.client.authServer = false
 72021-11-24 16:50:14 INFO main - tls.client.trustCertPath = null
 82021-11-24 16:50:14 INFO main - Using JDK SSL provider
 92021-11-24 16:50:15 INFO main - SSLContext created for server
102021-11-24 16:50:15 INFO NettyEventExecutor - NettyEventExecutor service started
112021-11-24 16:50:15 INFO main - Try to start service thread:FileWatchService started:false lastThread:null
122021-11-24 16:50:15 INFO FileWatchService - FileWatchService service started
132021-11-24 16:50:15 INFO main - The Name Server boot success. serializeType=JSON

启动 Broker

1> nohup sh bin/mqbroker -n localhost:9876 &
2> tail -f ~/logs/rocketmqlogs/broker.log 
3
42021-11-24 16:52:22 INFO main - The broker[localhost, 10.3.10.244:10911] boot success. serializeType=JSON and name server is localhost:9876
52021-11-24 16:52:32 INFO BrokerControllerScheduledThread1 - dispatch behind commit log 0 bytes
62021-11-24 16:52:32 INFO BrokerControllerScheduledThread1 - Slave fall behind master: 202890 bytes
72021-11-24 16:52:32 INFO brokerOutApi_thread_2 - register broker[0]to name server localhost:9876 OK
82021-11-24 16:53:02 INFO brokerOutApi_thread_3 - register broker[0]to name server localhost:9876 OK

安装 RocketMQ-Dashboard

可视化工具，可以在浏览器中查看消息队列的状态。

同样用源码安装，当然也可以用 docker 安装。

下载源码包

1 wget https://github.com/apache/rocketmq-dashboard/archive/refs/tags/rocketmq-dashboard-1.0.0.zip

编译运行

1
2> unzip rocketmq-dashboard-1.0.0.zip
3> cd rocketmq-dashboard-rocketmq-dashboard-1.0.0
4> mvn spring-boot:run

这时候会出现如下错误：

 1Caused by: org.apache.rocketmq.remoting.exception.RemotingConnectException: connect to null failed
 2 at org.apache.rocketmq.remoting.netty.NettyRemotingClient.invokeSync(NettyRemotingClient.java:394)
 3 at org.apache.rocketmq.client.impl.MQClientAPIImpl.getBrokerClusterInfo(MQClientAPIImpl.java:1333)
 4 at org.apache.rocketmq.tools.admin.DefaultMQAdminExtImpl.examineBrokerClusterInfo(DefaultMQAdminExtImpl.java:306)
 5 at org.apache.rocketmq.tools.admin.DefaultMQAdminExt.examineBrokerClusterInfo(DefaultMQAdminExt.java:257)
 6 at org.apache.rocketmq.dashboard.service.client.MQAdminExtImpl.examineBrokerClusterInfo(MQAdminExtImpl.java:204)
 7 at org.apache.rocketmq.dashboard.service.client.MQAdminExtImpl$$FastClassBySpringCGLIB$$a15c4ca6.invoke(<generated>)
 8 at org.springframework.cglib.proxy.MethodProxy.invoke(MethodProxy.java:218)
 9 at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.invokeJoinpoint(CglibAopProxy.java:769)
10 at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:163)
11 at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.proceed(CglibAopProxy.java:747)
12 at org.springframework.aop.aspectj.MethodInvocationProceedingJoinPoint.proceed(MethodInvocationProceedingJoinPoint.java:88)
13 at org.apache.rocketmq.dashboard.aspect.admin.MQAdminAspect.aroundMQAdminMethod(MQAdminAspect.java:52)
14 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
15 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
16 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
17 at java.lang.reflect.Method.invoke(Method.java:498)

明显是连不上服务器，需要修改配置文件：

1> cd src/main/resources/

打开 application.properties 文件

 1#
 2# Licensed to the Apache Software Foundation (ASF) under one or more
 3# contributor license agreements. See the NOTICE file distributed with
 4# this work for additional information regarding copyright ownership.
 5# The ASF licenses this file to You under the Apache License, Version 2.0
 6# (the "License"); you may not use this file except in compliance with
 7# the License. You may obtain a copy of the License at
 8#
 9# http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16#
17
18server.address=0.0.0.0
19server.port=8080
20
21### SSL setting
22#server.ssl.key-store=classpath:rmqcngkeystore.jks
23#server.ssl.key-store-password=rocketmq
24#server.ssl.keyStoreType=PKCS12
25#server.ssl.keyAlias=rmqcngkey
26
27#spring.application.index=true
28spring.application.name=rocketmq-dashboard
29spring.http.encoding.charset=UTF-8
30spring.http.encoding.enabled=true
31spring.http.encoding.force=true
32logging.level.root=INFO
33logging.config=classpath:logback.xml
34#if this value is empty,use env value rocketmq.config.namesrvAddr NAMESRV_ADDR | now, you can set it in ops page.default localhost:9876
35rocketmq.config.namesrvAddr=
36#if you use rocketmq version < 3.5.8, rocketmq.config.isVIPChannel should be false.default true
37rocketmq.config.isVIPChannel=
38#timeout for mqadminExt, default 5000ms
39rocketmq.config.timeoutMillis=
40#rocketmq-console's data path:dashboard/monitor
41rocketmq.config.dataPath=/tmp/rocketmq-console/data
42#set it false if you don't want use dashboard.default true
43rocketmq.config.enableDashBoardCollect=true
44#set the message track trace topic if you don't want use the default one
45rocketmq.config.msgTrackTopicName=
46rocketmq.config.ticketKey=ticket
47
48#Must create userInfo file: ${rocketmq.config.dataPath}/users.properties if the login is required
49rocketmq.config.loginRequired=false
50
51#set the accessKey and secretKey if you used acl
52#rocketmq.config.accessKey=
53#rocketmq.config.secretKey=
54rocketmq.config.useTLS=false

根据注释我们得知，需要将 rocketmq.config.namesrvAddr 设置为：localhost:9876, 再次启动成功。

访问：http://localhost:8080/ ，当然你也可以修改地址或者更改端口号。同样是修改 application.properties 文件，修改成类似这样的配置：

1server.port=8083
2server.servlet.context-path=/rocketmq-dashboard

测试消息的发送和接收

1> export NAMESRV_ADDR=localhost:9876
2> sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer
3 SendResult [sendStatus=SEND_OK, msgId= ...
4
5> sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer
6 ConsumeMessageThread_%d Receive New Messages: [MessageExt...

关闭 nameServer 和 broker

1> sh bin/mqshutdown broker
2The mqbroker(36695) is running...
3Send shutdown request to mqbroker(36695) OK
4
5> sh bin/mqshutdown namesrv
6The mqnamesrv(36664) is running...
7Send shutdown request to mqnamesrv(36664) OK

其他高可用部署方式

多 Master 模式
多 Master 多 Slave 模式-异步复制
多 Master 多 Slave 模式-同步双写

具体部署方式可参考：文档

这里贴一个比较完整的生产 K8S 部署方案：

https://cloud.tencent.com/developer/article/1785729

上面这个方案是一个双主双从的配置，每个 statefulset 只有一个副本，每个 Pod 拥有自己的配置文件，根据 RocketMQ 文档的说明来配置，没有什么问题。但当我们要扩展多 Master, 多 Slave 的时候，就会比较麻烦，要再建 Master Slave 对，增加 statefulset。

下面有一个部署技巧可以解决这个的问题。

通过 statefulset 副本扩展集群规模

“

以上 Broker 与 Slave 配对是通过指定相同的 BrokerName 参数来配对，Master 的 BrokerId 必须是 0，Slave 的 BrokerId 必须是大于 0 的数。

”

根据文档得知 Master 和 Slave 是根据 BrokerName 来配对的，所以上面的部署配置中也对同一对的主从设置了相同的 BrokerName。

如果没有配置 BrokerName 有默认值吗？

我们来看下 RocketMQ 的源码：

 1
 2public class BrokerConfig {
 3 private static final InternalLogger log = InternalLoggerFactory.getLogger(LoggerName.COMMON_LOGGER_NAME);
 4
 5 private String rocketmqHome = System.getProperty(MixAll.ROCKETMQ_HOME_PROPERTY, System.getenv(MixAll.ROCKETMQ_HOME_ENV));
 6 @ImportantField
 7 private String namesrvAddr = System.getProperty(MixAll.NAMESRV_ADDR_PROPERTY, System.getenv(MixAll.NAMESRV_ADDR_ENV));
 8 @ImportantField
 9 private String brokerIP1 = RemotingUtil.getLocalAddress();
10 private String brokerIP2 = RemotingUtil.getLocalAddress();
11 @ImportantField
12 private String brokerName = localHostName();
13 @ImportantField
14 private String brokerClusterName = "DefaultCluster";
15
16 */
17 @ImportantField
18 private boolean aclEnable = false;
19
20 private boolean storeReplyMessageEnable = true;
21
22 private boolean autoDeleteUnusedStats = false;
23
24 public static String localHostName() {
25 try {
26 return InetAddress.getLocalHost().getHostName();
27 } catch (UnknownHostException e) {
28 log.error("Failed to obtain the host name", e);
29 }
30
31 return "DEFAULT_BROKER";
32 }

可见，brokerName 有默认值，即如果没有主动 set brokerName，那么获取的是 localhostName。

pod 的 hostname 即为 pod 的名字，如果我们的 pod 名字是 broker-0，那么它的 hostname 就是 broker-0。联系上面 RocketMQ 的源码，brokerName 的值如果不设置拿到的就是 hostname, 即 pod Name。

由于我们部署 RocketMQ 时用的是有状态服务 (statefulset)，statefulset 的 Pod 的命名是有规则的：

“

对于一个拥有 N 个副本的 StatefulSet，Pod 被部署时是按照 {0 …… N-1} 的序号顺序创建的。

”

于是我们就可以利用 statefulset 的命名规则进行集群的扩展了，例如我要设置一个双主双从的集群，那么只需要将 master 和 slave 的 statefulset 的副本数设置为 2 就可以了，结果类似这样：

1rocketmq-broker-master-0 1/1 Running 1 462d
2rocketmq-broker-master-1 1/1 Running 0 462d
3rocketmq-broker-slave-0 1/1 Running 1 462d
4rocketmq-broker-slave-1 1/1 Running 0 462d

可见，根据命名规则 RocketMQ 的 Master 和 Slave 可以根据 brokerName（即 pod name）配对正确。那么如果我想要扩展集群，那么我只需要把 master 和 slave 的 statefulset 的副本数设置为 2、3、4、5… 就可以了。

以上就完成了只需要改两个 statefulset 的副本数就可以扩展集群的操作。一个小技巧分享给大家。

DevOps on 小盒子的技术分享

我用两句中文，让 Claude Code 帮我画了10张出版级技术图

OpenAI 开源 Symphony：AI 不再只是写代码，而是开始接管“工作流”

一、Symphony 到底是什么？

二、它为什么比“会写代码”更进一步？

三、每个 issue 一个 workspace：这是 Symphony 最值钱的工程细节

四、WORKFLOW.md 才是灵魂：把 Prompt 升级成 repo 内契约

五、为什么参考实现偏偏选了 Elixir？

六、真正的前提不是更强模型，而是 Harness Engineering

七、它的边界也必须讲清楚

结语

提示词缓存:让 LLM 成本降 10 倍

到底什么是 Cached Token ？

LLM 架构

Tokenizer (分词器 / 切词器)

Embedding (嵌入层)

Transformer (变换器 / 核心处理层)

Output (输出层)

实现原理

想省钱，要这样用

常见 “踩坑清单”

缓存能活多久 / 怎么保持

落地建议

实际应用场景

快速安装 ClickHouse

概述

安装

克隆 HyperDX 仓库

docker compose 启动

运行

客户端连接

数据库初始化

RAG系统效果难评？2025年必备的RAG评估框架与工具详解

前言：RAG崛起，评估成关键

一、 RAG评估的独特挑战与核心指标

独特挑战

核心 RAG 评估指标

二、 主流RAG评估工具深度解析 (2025年精选)

1. RAGAS (RAG Assessment)

2. DeepEval

3. TruLens

4. LLM-RAG-Eval

5. RAGChecker

6. MLflow LLM Evaluate

7. Arize AI Phoenix

补充：LangSmith

三、 如何选择与组合RAG评估工具？

RAG 评估工具组合策略

四、 RAG评估的未来展望

最后

RAG 实践- Ollama+RagFlow 部署本地知识库

前言

RagFlow的安装和部署

前置条件

安装

注册登录

配置 Ollama 连接大模型

创建知识库

聊天

思考

参考

为什么 ~ 代表 macOS 和 Linux 上的主文件夹？

Make Jar, Not War.

war 包的理由

jar 的时代

方便

云原生友好

版本控制

易于扩展

参考

自顶向下学习 RocketMQ（三）：消息存储

前言

消息存储

前知识

存储架构

CommitLog

ConsumeQueue

indexFile

总结

RocketMQ 文件存储模型层次结构

二、主流RAG评估工具深度解析 (2025年精选)

三、如何选择与组合RAG评估工具？