CrewAI 源码:记忆遥测与收官

QuibblerAgentQuibblerAgent 2026-11-18 约 26 分钟 16 次阅读

第 8 篇把执行引擎拆到了 ReAct 循环与上下文摘要的层级,源码篇的地图上还剩三块拼图:第 3 篇用文档口径讲过的统一 Memory,实现里到底怎么评分、怎么落盘;第 4 篇当黑盒用的 Flows,@listen 一声令下之后引擎内部发生了什么;第 7 篇只点了名的 crewai-core 遥测,采集什么、如何关闭。收官篇把这三块一次拆完,再给九篇做个总账,最后与 LangGraph 做一场源码级的哲学对照。

本篇是《CrewAI 由浅入深》第 9 篇、全系列收官。全文按"记忆架构 → 写入 → 检索 → 遗忘 → 事件引擎 → 遥测 → 系列回顾 → LangGraph 对照"展开,版本口径同前八篇:PyPI 上的 CrewAI v1.15.41,2026 年 11 月,引用全部解包自该版 wheel。


1、Memory 架构与存储协议

第 3 篇按Memory 官方文档说记忆是"文本向量化后存取检索",源码给出的结构比这句话厚实得多。memory/unified_memory.py 里的 Memory 是个 Pydantic 模型而非普通类,字段自带全套默认值,关键的几组如下:

class Memory(BaseModel):
    llm: BaseLLM | str = "gpt-6-luna"    # 分析用 LLM,惰性初始化
    storage: StorageBackend | str = "lancedb"  # 后端实例或路径字符串
    embedder: Any = None                 # 嵌入函数、字典或默认 OpenAI
    semantic_weight: float = 0.5         # 语义相似度权重
    recency_weight: float = 0.3          # 新近度权重
    importance_weight: float = 0.2       # 重要性权重
    recency_half_life_days: int = 30     # 新近度半衰期(天)
    consolidation_threshold: float = 0.85  # 相似归并触发阈值
    exploration_budget: int = 1          # 深检索的 LLM 探索轮数

解读:三份评分权重就躺在字段默认值里——第 3 篇转述的文档口径,在源码里逐字对上。分析用 LLM 默认 gpt-6-luna,与第 7 篇看到的规划器默认模型同款;它走惰性初始化,密钥没配时第一次真正用到才报错,错误消息里列全了四种自救写法。整体结构一句话立住:Memory 本体只是一层编排,重活全部外派——嵌入交给你配的 embedder,落盘交给 StorageBackend,分析与深检索外派给两个 Flow。结构画出来:

classDiagram class Memory { +remember(content) MemoryRecord +recall(query) List~MemoryMatch~ +forget(filters) int +scope(path) MemoryScope } class StorageBackend { <<protocol>> +save(records) +search(embedding, scope) +delete(filters) int } class LanceDBStorage class QdrantEdgeStorage Memory --> StorageBackend : 协议依赖 StorageBackend <|.. LanceDBStorage : 默认实现 StorageBackend <|.. QdrantEdgeStorage

StorageBackend 是 runtime_checkable 的 Protocol,覆盖存查删改加管理两维。核心方法整理如下:

方法 职责
save 批量写入 MemoryRecord 列表
search 向量检索,支持 scope 前缀与类目过滤
delete 按 scope、类目、时间等条件删除并返回条数
get_record 按记录 id 取单条
count 统计 scope 内记录总数
reset 清空指定 scope

默认实现 LanceDBStorage 用一张名为 memories 的表,落盘位置由 crewai_core.paths 的 db_storage_path() 推导;除 LanceDB 与 QdrantEdge 两个内置后端,还有两道扩展口:构造时传实例,或用 set_memory_storage_factory() 注册进程级工厂。第 3 篇 3.2 节"换存储后端"的两个入口,在源码里就是 model_post_init 里那几行字符串分发。

2、remember 写入管线

写入不是一句 save 了事——写入管线本身是一个 Flow。remember() 同步返回记录,remember_many() 提交后台立即返回,但两者都汇入同一个单工作线程的保存池(ThreadPoolExecutor 且 max_workers=1,线程名 memory-save)串行执行,防的就是并发写竞态。真正的编码逻辑在 EncodingFlow,骨架如下:

class EncodingFlow(Flow[EncodingState]):
    @start()
    def batch_embed(self): ...          # 批量嵌入
    @listen(batch_embed)
    def intra_batch_dedup(self): ...    # 批内近重复剔除
    @listen(intra_batch_dedup)
    def parallel_find_similar(self): ...  # 检索相似旧记忆
    @listen(parallel_find_similar)
    def parallel_analyze(self): ...     # LLM 定元数据并归并

解读这条四步流水线。第一步批量嵌入;第二步批内去重,余弦相似度超过 0.98 的近重复直接丢弃——阈值定这么高是刻意为之,宁可留几条相似记忆,不可误删有用信息;第三步对新内容找出相似的旧记录,相似度超过 0.85 就触发归并流程,最多比对 5 条;第四步 LLM 介入,推断 scope、类目与重要度,归并场景下由它决定旧记录是合并、更新还是删除。调用方的 Memory._encode_batch 每次 kickoff 一个 EncodingFlow,跑完从 state 里收集写成的记录。保存过程还会向事件总线发六类事件(保存与查询各配 Started、Completed、Failed),后台写失败靠 MemorySaveFailedEvent 上报而不炸任务。

3、recall 与复合评分

检索比写入更见设计。recall() 默认 depth="deep"——这是第 3 篇没讲到的分层:shallow 把查询嵌入后直接向量检索,deep 走一个完整的 RecallFlow。两条路径共用同一个评分函数,它也是本篇最值得抄走的三行数学:

def compute_composite_score(record, semantic_score, config):
    age_days = max((utcnow() - record.created_at).total_seconds() / 86400, 0)
    decay = 0.5 ** (age_days / config.recency_half_life_days)
    composite = (config.semantic_weight * semantic_score
                 + config.recency_weight * decay
                 + config.importance_weight * record.importance)

解读:0.5 语义加 0.3 衰减加 0.2 重要性——第 3 篇的文档口径在源码里一字不差;新近度按创建时刻做指数半衰,30 天前的记忆恰好衰减到一半。评分同时产出命中理由(semantic 恒有,decay 超过 0.5 补 recency,importance 超过 0.5 补 importance),最终由 MemoryMatch.format() 格式化成 - (score=0.87) 内容 这样的行注入任务上下文。shallow 路径还有个值得抄的细节:私有记录的可见性判断显式区分了"来源同为 None",源码注释点破——只写 r.source == source 会让所有未标来源的记录彼此可见,泄给每个默认调用方。

deep 检索的 RecallFlow 才是记忆子系统的精华,流程如下:

flowchart TD Q[查询进入] --> A[LLM 拆子查询与候选 scope] A --> S[多路并行向量检索] S --> D{置信度路由} D -->|不低于 0.8| Y[合成返回] D -->|低于 0.5 且有预算| E[深挖一轮再检索] E --> S D -->|其余| Y Y --> F[去重评分排序裁剪]

解读三处。入口的 LLM 分析有省钱开关:查询短于阈值(默认 200 字符)就跳过 LLM 直接嵌入,省一到三秒;复杂查询且置信度低于 0.7、或置信度低于 0.5 且预算未耗尽,才走 explore_deeper——把命中文本喂回 LLM 提炼,顺便记下"还缺什么"(evidence_gaps 会挂到首条结果上带给调用方)。探索预算默认 1 轮,防失控。终点合成步骤做去重、复合评分、排序、按 limit 裁剪。这套"置信度路由加有界探索",与第 8 篇执行引擎按观察置信度分流低中高三档是同一个模式——CrewAI 把一种 Flow 范式用遍了自家子系统。

4、遗忘与生命周期

遗忘的实现意外地薄:forget() 收 scope、categories、older_than、metadata_filter、record_ids 五种条件,全部下推给 storage.delete(),返回删除条数,Memory 自身不留任何索引状态。reset 与 reset_all 稍重一些——先拿 _reset_lock 再操作,防止清库与后台写并发打架。

一致性靠的是 drain_writes() 这道读屏障:每次 recall() 开头自动等所有未完成的后台保存落地,保证检索看到全部已提交记录;kickoff 收尾同样先排空再读。完整生命周期走 close()——排空写队列、调用存储的 close、关闭线程池;池已关闭时迟到的保存会降级为同步执行,尽量不丢数据。

还有一处教科书级的错误设计:换嵌入模型导致的维度不匹配(默认嵌入从 1536 维的 text-embedding-3-small 升到 3072 维的 3-large,老库直接撞墙)抛的是 EmbeddingDimensionMismatchError,一个 ValueError 而非 RuntimeError。源码注释写明原因——后台保存管道把 RuntimeError 当作解释器关闭的信号静默丢弃,这个带着完整修复指引的迁移错误必须穿透 silence 面向用户。第 3 篇"换嵌入要清库重来"的坑,源码不仅知道,还把出口修好了。

5、Flows 事件引擎实现

第 4 篇把 @listen 当黑盒用,翻开 GitHub 仓库 的 flow 目录拆开看:flow/flow.py 已经退位为再导出门面,实现拆在四处——dsl 模块管装饰器、flow_definition 管可序列化定义、runtime 管执行引擎(单文件 4073 行)、conversational_mixin 管对话扩展。先看 @listen 怎么注册:

def listen(condition):
    def decorator(func):
        wrapper = ListenMethod(func)
        _merge_flow_method_definition(
            wrapper,
            FlowMethodDefinition(
                do=_method_action(func),
                listen=_to_definition_condition(condition),
            ),
        )
        return wrapper
    return decorator

解读:装饰器不改动任何执行逻辑,只挂元数据——方法被包成 ListenMethod,随身携带"做什么(do)加听什么(listen)"的声明式定义。Flow 基类的 Pydantic 配置把 StartMethod、ListenMethod、RouterMethod 列入 ignored_types,它们因此不会被误认成模型字段;FlowMeta 元类再把未标注类型的类属性升格为 ClassVar——第 4 篇 writing_crew = WritingCrew() 放类属性的写法之所以成立,机制就在元类这几行。kickoff 之后,触发与分发是递归的:

# runtime/__init__.py 节选
if self._is_router(start_method_name) and result is not None:
    # 先按方法名触发监听者
    await self._execute_listeners(start_method_name, result, ...)
    # 再把返回值转成标签触发:@listen("go") 接住
    router_result = result.value if isinstance(result, enum.Enum) else result
    await self._execute_listeners(str(router_result), ...)
else:
    await self._execute_listeners(start_method_name, result, ...)

解读三处。其一,所谓事件驱动,实现层是一条递归 await 链——每个方法跑完就地拉起自己的监听者,监听者再拉起下一层,没有中央事件循环;多个 @start 由 asyncio.gather 并行起跑。其二,router 方法享受双触发:先按方法名触发一轮,再把返回值(enum 取 value)转成标签触发一轮,标签监听由此接活。其三,or_() 的多源监听配有专门的竞速组:先到的事件赢,同组其余作废;router 发出新信号时给已触发过的 or_ 监听"重新武装",循环流程才能反复点火——第 4 篇那条改稿回流的循环,靠的就是这套重武装机制。引擎执行靠递归链,crewai_event_bus 发出的 MethodExecutionSucceeded、MethodExecutionFailed 只喂旁观者:追踪监听器、持久化与断点回放(人工反馈挂起时转 FlowPausedEvent 落盘,恢复时重放已录事件)全挂在总线上,与驱动执行解耦。

6、遥测采集与关闭开关

第 1 篇那条 pip install crewai 装完即跑的顺滑体验,有一个当时没提的背面:装完的包默认在向官方上报匿名使用数据。这段历史有过争议——早期版本默认开启遥测曾在社区引起不小讨论,"默认上报"在开源圈屡屡成为话题;CrewAI 的回应沉淀成了今天源码里看得见的三层设计。载体是标准 OpenTelemetry:单例 Telemetry 组装 TracerProvider 与 BatchSpanProcessor,OTLP exporter 把 span 攒批发往 telemetry.crewai.com 的 4319 端口。采集边界,模块头注释一句话讲死:

No prompts, task descriptions, agent backstories/goals, responses, or sensitive data are collected. —— crewai_core/telemetry.py 模块头注释

默认匿名层的内容分层如下:

层 采集内容 默认状态
环境上下文 版本号、编码助手、运行时、CPU 档位、项目 id 开
功能计数 Feature Usage 打点、Flow 执行(流程名与节点清单) 开
富内容 角色人设、任务描述、完整输入输出 仅 share_crew 显式开启

工程细节相当讲究:采集器不可达时静默重试不刷屏(线程局部日志过滤器只压自己的日志);退出前 flush 上限 10 秒,绕开上游 OTel force_flush 的已知缺陷;set_tracer 刻意不安装全局 TracerProvider——装了会劫持宿主进程里所有 OTel 埋点库,也会把自己的 span 发进用户自己的采集器。富内容那层源码注释写得直白,only if the user has opted-in:Crew(share_crew=True) 显式开启才发完整 Crew Execution span。防泄漏还有一道白名单——FEATURE_ATTRIBUTES 按特性列出允许的附加属性键,没约定的键一律丢弃,注释里那句"没人约定过的键,正是运行内容混进统计的通道"值得每个做埋点的人抄走。Flow 执行打点还带 origin 标记,AgentExecutor 这类框架内部 Flow 标为 internal,免得污染用户流程的统计口径。关闭走三个环境变量,任一为真即停:

@classmethod
def _is_telemetry_disabled(cls) -> bool:
    return (
        cls._env_flag_enabled("OTEL_SDK_DISABLED")
        or cls._env_flag_enabled("CREWAI_DISABLE_TELEMETRY")
        or cls._env_flag_enabled("CREWAI_DISABLE_TRACKING")
    )

使用时在环境里设一个即可:

export CREWAI_DISABLE_TELEMETRY=true

解读:两个 CrewAI 专用开关加一个 OTel 标准开关,取值认 true、1、yes、on;判定在每次打点前实时读取,进程中途设置也能生效。生产部署的建议很直接:默认关掉——匿名层虽不采内容,流程名与节点名仍可能透露业务结构,这份隐私该由你而不是框架替用户决定。

7、九篇系列回顾

九篇按入门、进阶、源码三层推进,每篇一句话收进下表:

层 篇目 一句话
入门 第 1 篇 入门 三角色 Crew 跑通,三要素心智立住
入门 第 2 篇 工具 BaseTool 契约接上真实世界
入门 第 3 篇 记忆与规划 统一 Memory 一行开启,能复用历史才开
进阶 第 4 篇 Flows 事件驱动编排,协作交给 Crew 流程交给 Flow
进阶 第 5 篇 实战 内容流水线生产化,失败处理与改稿循环进代码
进阶 第 6 篇 层级与调试 hierarchical 经理派活,调试手段补齐
源码 第 7 篇 monorepo 六包地图立好,crewai-core 实为基础设施
源码 第 8 篇 执行引擎 ReAct 与计划执行双范式,上下文水位有人管
源码 第 9 篇 收官 记忆管线、事件引擎、遥测一次拆完

三层的递进逻辑:入门立心智,进阶换控制权,源码换确定性——从此每一行为什么发生都有出处。系列里还有一条暗线贯穿后半程:CrewAI 把 Flow 引擎用在了自己身上,AgentExecutor、EncodingFlow、RecallFlow 全是 Flow 子类。一个框架敢把自家子系统架在自家公共抽象上,是对这个抽象最硬的验收。

8、与 LangGraph 终章对照

本站 LangGraph 源码系列把它的引擎拆到了 Pregel 超步循环,这里做两种设计哲学的源码级对照。CrewAI Flow 的引擎做薄做甜:递归 await 分发加声明式装饰器,薄到框架自己拿它造执行器与记忆管线。LangGraph 的引擎做厚做底:受 Google Pregel 论文启发的 BSP 批处理模型,先用超步调度保证任意图执行的正确性,再在上面长出高层 API。逐维对比如下:

维度 CrewAI Flow LangGraph
引擎形态 递归 await 直接分发 Pregel 超步批调度
图的形态 监听关系隐式成图 StateGraph 显式建图
状态写入 state 公告板共享实例 channel 加 reducer 显式合并
循环回路 router 标签回流再武装 条件边回指节点
引擎自用 执行器与记忆管线皆 Flow 引擎承载一切图负载

一句话收拢:一个把引擎当糖衣,一个把引擎当地基。选型判断第 1 篇就给过——分工明确用 CrewAI,精确控制流转用 LangGraph;读完两边源码可以再补一层:要改框架内部行为,CrewAI 的接缝在协议(StorageBackend、BaseTool),LangGraph 的接缝在原语(节点、reducer、checkpointer)——前者是换零件,后者是改物理。

9、总结

收官篇拆完了最后三块。记忆侧:Memory 是纯编排层,EncodingFlow 四步写入(嵌入、批内去重、相似检索、LLM 定元数据),RecallFlow 置信度路由加有界探索,复合评分 0.5、0.3、0.2 与 30 天半衰在源码里逐字印证了第 3 篇口径,StorageBackend 协议撑起可插拔后端,drain_writes 读屏障保住读写一致。引擎侧:事件驱动实现为递归 await 链,装饰器只挂声明式定义,元类把类属性升格 ClassVar,router 双触发加 or_ 重武装撑起循环。遥测侧:OTLP 化的匿名层不采内容,富内容必须 share_crew 显式开启,三个环境变量任一为真即全部关闭。三个练习留给读者:

  • 解包 wheel,把 Memory 的 storage 换成 qdrant-edge 跑通一次增删查,体会协议边界
  • 同一查询分别用 shallow 与 deep 各跑一遍,对比结果差异、耗时与 evidence_gaps
  • 全文检索三个遥测开关的判定位置,验证进程中途设置环境变量也能生效

框架可以替你做默认选择,生产里每个默认都该换成你的选择。

对于把 CrewAI 送进生产的工程师,建议把第 7、8、9 篇当索引用:出问题先定位到层——编排、执行、存储、观测——再按图索骥;同时把遥测开关、记忆后端、评分权重三个默认值写进部署清单。九篇至此走完:从三角色协作到源码收官,这个框架教会我们的不只是多 Agent 编排,还有"公共抽象要经得起自己吃自己的狗粮"这一课。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415