面向AI的数据转换

专为AI设计的超高效数据转换框架，核心引擎采用Rust编写。开箱即用支持增量处理和数据血缘追踪。开发者效率极高，开箱即产即可投入生产。

⭐ 点个星帮助我们成长吧！

CocoIndex让使用AI进行数据转换变得轻而易举，并能轻松保持源数据与目标数据同步。无论您是在构建向量索引、创建用于上下文工程的知识图谱，还是一切自定义数据转换任务——它远不止SQL那么简单。

超高的开发效率

只需用约100行Python代码在数据流中声明转换逻辑：

# 导入
data['content'] = flow_builder.add_source(...)

# 转换
data['out'] = data['content']
    .transform(...)
    .transform(...)

# 收集数据
collector.collect(...)

# 导出到数据库、向量数据库、图数据库……
collector.export(...)

CocoIndex遵循数据流编程模型的理念。每次转换都仅基于输入字段生成新字段，不存在隐藏状态或值的突变。每一步转换前后的数据均可观察，开箱即有数据血缘追踪功能。

尤其重要的是，开发者无需显式地通过创建、更新或删除来改变数据，只需为一组源数据定义转换规则或公式即可。

即插即用的组件模块

针对不同来源、目标和转换场景，内置了原生组件。接口标准化，只需一行代码即可切换不同组件，就像拼装积木一样简单。

数据新鲜度

CocoIndex能够毫不费力地保持源数据与目标数据同步。

它开箱即用支持增量索引：

• 源数据或逻辑变更时，仅需最小化重新计算。
• 只对必要的部分进行（再）处理；尽可能复用缓存。

快速入门

如果您是CocoIndex的新用户，建议先查看以下内容：

• 📖 文档
• ⚡ 快速入门指南
• 🎬 快速入门视频教程

安装步骤

1. 安装CocoIndex Python库

pip install -U cocoindex

2. 如果您还没有PostgreSQL，请安装PostgreSQL。CocoIndex利用它来进行增量处理。

3. （可选）安装Claude Code技能以提升开发体验。在Claude Code中运行以下命令：

/plugin marketplace add cocoindex-io/cocoindex-claude
/plugin install cocoindex-skills@cocoindex

定义数据流

请按照快速入门指南来定义您的第一个索引流程。一个示例流程如下：

@cocoindex.flow_def(name="TextEmbedding")
def text_embedding_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope):
    # 添加一个数据源，从目录中读取文件
    data_scope["documents"] = flow_builder.add_source(cocoindex.sources.LocalFile(path="markdown_files"))

    # 添加一个收集器，用于将数据导出到向量索引
    doc_embeddings = data_scope.add_collector()

    # 转换每个文档的数据
    with data_scope["documents"].row() as doc:
        # 将文档拆分为多个块，并存储在`chunks`字段中
        doc["chunks"] = doc["content"].transform(
            cocoindex.functions.SplitRecursively(),
            language="markdown", chunk_size=2000, chunk_overlap=500)

        # 转换每个块的数据
        with doc["chunks"].row() as chunk:
            # 对该块进行嵌入，并将结果存储在`embedding`字段中
            chunk["embedding"] = chunk["text"].transform(
                cocoindex.functions.SentenceTransformerEmbed(
                    model="sentence-transformers/all-MiniLM-L6-v2"))

            # 将该块收集到收集器中。
            doc_embeddings.collect(filename=doc["filename"], location=chunk["location"],
                                   text=chunk["text"], embedding=chunk["embedding"])

    # 将收集的数据导出到向量索引。
    doc_embeddings.export(
        "doc_embeddings",
        cocoindex.targets.Postgres(),
        primary_key_fields=["filename", "location"],
        vector_indexes=[
            cocoindex.VectorIndexDef(
                field_name="embedding",
                metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY)])

它定义了一个如下的索引流程：

🚀 示例与演示

示例	描述
文本嵌入	使用嵌入对文本文档进行索引，以支持语义搜索
代码嵌入	使用嵌入对代码进行索引，以支持语义搜索
PDF 嵌入	解析 PDF 并对文本内容进行嵌入索引，以支持语义搜索
PDF 元素嵌入	从 PDF 中提取文本和图像；使用 SentenceTransformers 对文本进行嵌入，使用 CLIP 对图像进行嵌入；并将结果存储在 Qdrant 中，以实现多模态搜索
手册 LLM 提取	使用 LLM 从手册中提取结构化信息
Amazon S3 嵌入	索引来自 Amazon S3 的文本文档
Azure Blob 存储嵌入	索引来自 Azure Blob 存储的文本文档
Google Drive 文本嵌入	索引来自 Google Drive 的文本文档
会议记录转知识图谱	从 Google Drive 中提取结构化的会议信息，并构建知识图谱
文档转知识图谱	从 Markdown 文档中提取关系，并构建知识图谱
嵌入到 Qdrant	将文档索引到 Qdrant 集合中，以支持语义搜索
嵌入到 LanceDB	将文档索引到 LanceDB 集合中，以支持语义搜索
FastAPI 服务器与 Docker	在 Docker 化的 FastAPI 设置中运行语义搜索服务器
产品推荐	使用 LLM 和图数据库构建实时产品推荐
使用视觉 API 进行图像搜索	使用视觉模型为图像生成详细描述，并对其进行嵌入；通过 FastAPI 实现实时更新的语义搜索，并在 React 前端上展示
人脸识别	识别图像中的人脸并构建嵌入索引
论文元数据	对 PDF 文件中的论文进行索引，并为每篇论文构建元数据表
多格式索引	使用 ColPali 从 PDF 和图像中构建视觉文档索引，以支持语义搜索
自定义源 HackerNews	使用 CocoIndex 自定义源 对 HackerNews 的帖子和评论进行索引
自定义输出文件	使用 CocoIndex 自定义目标 将 Markdown 文件转换为 HTML 文件并保存到本地目录
患者入院表单提取	使用 LLM 从不同格式的患者入院表单中提取结构化数据
HackerNews 热门话题	使用 CocoIndex 自定义源 和 LLM 从 HackerNews 的帖子和评论中提取热门话题
使用 BAML 提取患者入院表单	使用 BAML 从患者入院表单中提取结构化数据
使用 DSPy 提取患者入院表单	使用 DSPy 从患者入院表单中提取结构化数据

更多内容即将推出，敬请期待 👀！

📖 文档

有关详细文档，请访问 CocoIndex 文档，其中包括快速入门指南。

🤝 贡献

我们非常欢迎社区的贡献 ❤️。有关如何参与贡献或在开发环境中运行该项目的详细信息，请参阅我们的贡献指南。

👥 社区

热烈欢迎您加入！我们非常期待来自社区的各种贡献——无论是代码改进、文档更新、问题报告、功能请求，还是在 Discord 上的讨论。

在这里加入我们的社区：

• 🌟 在 GitHub 上关注我们
• 👋 加入我们的 Discord 社区
• ▶️ 订阅我们的 YouTube 频道
• 📜 阅读我们的博客文章

支持我们

我们一直在不断改进，更多的功能和示例即将推出。如果您喜欢这个项目，请在 GitHub 仓库中给我们点个赞 ⭐ ，以便及时了解最新动态并帮助我们成长。

许可证

CocoIndex 采用 Apache 2.0 许可证。

CocoIndex 快速上手指南

CocoIndex 是一个专为 AI 打造的高性能数据转换框架，核心引擎由 Rust 编写。它支持增量处理和完整的数据血缘追踪，能够帮助开发者轻松构建向量索引、知识图谱或执行自定义数据转换，并保持源数据与目标数据的实时同步。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：Python 3.8 或更高版本
• 数据库依赖：PostgreSQL。CocoIndex 依赖 Postgres 进行状态管理和增量处理。如果您尚未安装，请参考 PostgreSQL 官方安装指南 或使用 Docker 快速启动：

  docker run --name cocoindex-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres
  

• 网络连接：首次运行时需下载模型或连接外部 API（如 HuggingFace），请确保网络通畅。

安装步骤

1. 安装 Python 库

使用 pip 安装最新版本的 CocoIndex：

pip install -U cocoindex

提示：国内用户若遇到下载缓慢，可指定清华或阿里镜像源： pip install -U cocoindex -i https://pypi.tuna.tsinghua.edu.cn/simple

2. (可选) 增强开发体验

如果您使用 Claude Code，可以安装官方插件以获得更好的代码辅助：

/plugin marketplace add cocoindex-io/cocoindex-claude
/plugin install cocoindex-skills@cocoindex

基本使用

CocoIndex 采用 Dataflow（数据流） 编程模型。您只需声明数据来源、转换逻辑和目标出口，无需手动管理数据的增删改查，框架会自动处理增量更新。

以下是一个最简单的示例：读取本地 Markdown 文件，将其分块并生成嵌入向量（Embedding），最后存入 Postgres 向量索引。

代码示例 (quickstart.py)

import cocoindex

@cocoindex.flow_def(name="TextEmbedding")
def text_embedding_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope):
    # 1. 添加数据源：读取本地目录下的 markdown 文件
    data_scope["documents"] = flow_builder.add_source(
        cocoindex.sources.LocalFile(path="markdown_files")
    )

    # 2. 添加收集器：用于收集处理后要导出的数据
    doc_embeddings = data_scope.add_collector()

    # 3. 定义转换逻辑
    with data_scope["documents"].row() as doc:
        # 将文档递归分割成块 (chunks)
        doc["chunks"] = doc["content"].transform(
            cocoindex.functions.SplitRecursively(),
            language="markdown", 
            chunk_size=2000, 
            chunk_overlap=500
        )

        # 对每个文本块进行向量化处理
        with doc["chunks"].row() as chunk:
            chunk["embedding"] = chunk["text"].transform(
                cocoindex.functions.SentenceTransformerEmbed(
                    model="sentence-transformers/all-MiniLM-L6-v2"
                )
            )

            # 收集结果字段
            doc_embeddings.collect(
                filename=doc["filename"], 
                location=chunk["location"],
                text=chunk["text"], 
                embedding=chunk["embedding"]
            )

    # 4. 导出到目标数据库 (Postgres) 并建立向量索引
    doc_embeddings.export(
        "doc_embeddings",
        cocoindex.targets.Postgres(), # 需配置环境变量 DATABASE_URL 指向您的 Postgres
        primary_key_fields=["filename", "location"],
        vector_indexes=[
            cocoindex.VectorIndexDef(
                field_name="embedding",
                metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY
            )
        ]
    )

if __name__ == "__main__":
    # 启动数据流服务
    cocoindex.default_server().serve()

运行流程

1. 创建一个名为 markdown_files 的文件夹，并放入一些 .md 测试文件。
2. 设置数据库连接环境变量（假设使用本地默认 Postgres）：

   export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
   

3. 运行脚本：

   python quickstart.py
   

启动后，CocoIndex 会自动执行全量索引，并监听文件变化。当您在 markdown_files 目录中新增或修改文件时，系统将仅重新计算受影响的部分（增量更新），保持数据实时同步。

---

更多高级用法（如连接 S3、构建知识图谱、自定义源/目标等），请参阅 官方文档。