CocoIndex实时、持续更新的上下文

     CocoIndex 是一个开源框架，它能够将代码库、文档、会议记录、PDF、视频及其他数据源转换为 AI 代理和 LLM 应用的实时、持续更新的上下文 —— 并且仅重新计算实际发生变化的内容。它基于高性能 Rust 核心构建，并提供 Python 优先的 SDK，让你只需声明目标状态的具体样貌，引擎便会自动处理增量变更检测、记忆化、协调以及容错执行。

编程模型：声明目标，而非差异

     CocoIndex 采用声明式、状态驱动的编程模型。你编写批处理风格的 Python 代码，将输出指定为源数据的纯函数 —— 目标状态 = 转换(源状态) —— 而引擎会计算出实现目标同步所需的最小插入、更新和删除操作集。如果你曾使用过 React、电子表格或物化视图，便会觉得这种心智模型非常熟悉：

范式	你声明的内容	引擎处理的内容
React	UI 作为状态的函数	仅重新渲染发生变化的部分
电子表格	单元格中的公式	输入变更时下游单元格重新计算
物化视图	源表上的 SQL 查询	数据变化时刷新视图
CocoIndex	目标状态作为源的函数	以最小差异进行增量同步

你完全不需要编写差异逻辑、状态管理或编排代码。CocoIndex 会自动增量运行你的流水线，并保持输出持续更新。

CocoIndex 采用分层系统结构：用于编写流水线的 Python SDK 位于 Rust 核心引擎之上，该引擎负责处理执行、状态管理和增量处理。引擎通过可插拔的连接器模型与外部系统进行通信。

项目结构

该仓库被组织为三个主要层级，每个层级在系统中承担不同的职责：

cocoindex/
├── python/cocoindex/          │   ├── _internal/             # 核心 SDK 内部机制 (App, mount API, function, memo)
│   ├── connectors/            # 来源与目标连接器模块 (18 个连接器)
│   ├── ops/                   # 内置操作 (文本、代码、嵌入、实体解析)
│   └── cli.py                 # CLI 入口 (cocoindex 命令)
├── rust/                      # Rust 核心引擎 — 性能关键的运行时
│   ├── core/                  # 引擎：执行、状态存储、记忆化、实时组件
│   ├── py/                    # PyO3 绑定 (Rust ↔ Python 桥接)
│   ├── ops_text/              # 文本操作 (拆分、分块)
│   ├── code_match/            # 通过 tree-sitter 实现感知 AST 的代码匹配
│   └── sdk/                   # 用于原生流水线编写的 Rust SDK
├── examples/                  # 20+ 个可运行的流水线示例 (Python 与 Rust)
└── docs/                      # 文档站点 (Astro + Starlight)

小试

5 分钟构建你的第一个 CocoIndex 流水线 —— 将 PDF 文件转换为 Markdown，并体验增量处理（仅重新处理实际发生更改的文件）。在本指南结束时，你将理解支撑每个 CocoIndex 应用的三层架构，并亲眼见证为什么 target_state = transformation(source_state) 是你唯一需要的心智模型。

你将构建什么

一个从本地目录读取 PDF 文件，使用 Docling 将每个文件转换为 Markdown，并将结果保存到输出文件夹的流水线。整个声明仅需约 30 行 Python 代码。你可以随时重新运行——仅更改的文件会被重新处理。

你可以从仓库中的 pdf_to_markdown 示例 下载示例文件。

CocoIndex 应用具有一致的三层架构。理解此结构是掌握该框架的关键：

CocoIndex 的核心价值主张是增量处理——仅重新计算增量部分。尝试以下三种场景：

操作	发生的情况
向 pdf_files/ 添加新 PDF	仅处理新文件
修改现有 PDF	仅重新处理更改的文件（通过内容指纹检测）
从 pdf_files/ 删除 PDF	自动删除相应的 .md 文件

# 添加文件，然后重新运行
cocoindex update main.py    # ← 仅转换新文件
 
# 修改文件，然后重新运行
cocoindex update main.py    # ← 仅重新转换更改的文件
 
# 删除文件，然后重新运行
rm pdf_files/example.pdf
cocoindex update main.py    # ← out/example.md 被自动删除