第 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。结构画出来:
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 才是记忆子系统的精华,流程如下:
解读三处。入口的 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 编排,还有"公共抽象要经得起自己吃自己的狗粮"这一课。

