0 · 阅读地图：先找到 TensorFlow 的主干
用模块边界和一条 matmul 调用链建立全局心智模型
TensorFlow 不是一层库
TensorFlow 的“产品体验”集中在 tensorflow/python，但真正决定执行语义的对象分布在多个层：
| 层 | 关键目录 | 核心问题 |
|---|---|---|
| Python API | tensorflow/python/ops、framework、eager | 参数转换、上下文、自动微分、函数追踪 |
| 组合与训练 | tensorflow/python/keras、distribute、data | 如何把算子组装成训练循环 |
| 公共 C++ 抽象 | tensorflow/core/framework、core/public | Tensor、Graph、OpKernel、Status 的稳定边界 |
| 本地运行时 | tensorflow/core/common_runtime | 设备放置、Executor、内存、函数库、Session |
| 图优化与编译 | tensorflow/core/grappler、tensorflow/compiler、tensorflow/core/ir | 如何重写、降低和编译计算图 |
| 部署 | tensorflow/lite、python/saved_model | 如何把模型变成可加载、可迁移的资产 |
| 工程 | tools、ci、third_party | 如何生成 API、构建二进制、跑测试和兼容依赖 |
一条 tf.matmul 的三种形态
Eager 形态：即时执行
x = tf.constant([[1., 2.]])
y = tf.constant([[3.], [4.]])
z = tf.matmul(x, y)从 Python 角度，最终目标是 tensorflow/python/eager/execute.py 的 quick_execute；从 C++ 角度，目标是当前 EagerContext 中的立即执行上下文、设备客户端和 kernel registry。
Graph 形态：先建图再执行
@tf.function
def f(x, y):
return tf.matmul(x, y)第一次调用时，polymorphic_function.Function 根据输入结构生成或复用 ConcreteFunction。追踪期间创建的是 FuncGraph，其中的 Tensor 是符号输出；真正执行发生在后续调用的函数图运行时。
编译/部署形态：把图换成另一种执行资产
Graph 可以被 Grappler 重写，经过 TF-MLIR 或 XLA 降低，最终由设备 runtime 执行；SavedModel、TFLite FlatBuffer 又会保留另一套接口和元数据。这里的关键不是“图永远不变”，而是每次转换都要维护输入输出签名、资源和副作用。
四个需要反复回查的对象
- Tensor：值、dtype、shape、设备和底层 buffer 的组合，不等于 NumPy 数组。
- Operation / Node：图模式中的操作节点，携带输入边、属性、输出类型与控制依赖。
- Function：Python 可调用对象、追踪缓存和一个或多个 ConcreteFunction 的外壳。
- Kernel：某个 op 在某个 device/type/attribute 组合上的真正实现。
源码锚点
tensorflow/python/framework/ops.py：SymbolicTensor、eager tensor 包装、Graph与默认图相关入口。tensorflow/python/eager/context.py：Python 侧Context、设备和线程本地执行选项。tensorflow/python/eager/polymorphic_function/polymorphic_function.py：Function与tf.function。tensorflow/core/framework/tensor.h：C++Tensor与TensorBuffer。tensorflow/core/framework/op_kernel.h：OpKernel/AsyncOpKernel接口。tensorflow/core/common_runtime/executor.cc：Graph Executor 的 ready-node 调度循环。
阅读时最容易犯的错
- 把 Python 文件当成“实现本体”：很多 Python 函数只负责规范化参数、选择 context，真正的计算在 C++ kernel。
- 把
tf.function当成单纯的 JIT 装饰器：它首先是一个 tracing + cache + signature 管理系统，JIT 只是可能的后续路径。 - 把 GraphDef 当成唯一 IR：TensorFlow 同时存在 GraphDef、FunctionDef、MLIR、XLA HLO、TFLite FlatBuffer 等表示。