cocoindex

CocoIndex 是一个面向 AI 的超高性能实时数据转换框架，具备增量处理能力。本技能（Skill）旨在帮助开发者使用 CocoIndex 库构建索引流程，从数据源提取数据、应用转换（切分、嵌入、LLM 提取），并导出到目标（向量数据库、图数据库、关系数据库）。

一、核心能力

• 编写索引流程：使用 Python 定义 ETL 流程。
• 创建自定义函数：构建可复用的转换逻辑。
• 操作流程：使用 CLI 或 Python API 运行和管理流程。

关键特性：

• 增量处理（仅处理变更数据）
• 实时更新（持续同步源变更到目标）
• 内置函数（文本切分、嵌入、LLM 提取）
• 多种数据源（本地文件、S3、Azure Blob、Google Drive、Postgres）
• 多种目标（Postgres+pgvector、Qdrant、LanceDB、Neo4j、Kuzu）

详细文档：https://cocoindex.io/docs/ ；文档搜索：https://cocoindex.io/docs/search?q=url%20encoded%20keyword

二、适用场景

当用户提出以下请求时使用本技能：

• “为我的文档构建向量搜索索引”
• “为代码/PDF/图像创建嵌入流程”
• “使用 LLM 提取结构化信息”
• “从文档构建知识图谱”
• “建立实时文档索引”
• “创建自定义转换函数”
• “运行/更新我的 CocoIndex 流程”

三、流程编写工作流

步骤 1：理解需求。需要澄清的问题包括：数据源在哪里、文件类型、变更频率；需要哪些转换（切分、嵌入、提取等）、使用哪个嵌入模型、是否需要自定义逻辑；结果导出到哪里、模式定义、是否需要向量搜索。

步骤 2：设置依赖。基础依赖为 cocoindex。可选 extras：cocoindex[embeddings] 用于 SentenceTransformer 嵌入；cocoindex[colpali] 用于 ColPali 图像/文档嵌入；cocoindex[lancedb] 用于 LanceDB 目标；多个 extras 可组合，如 cocoindex[embeddings,lancedb]。用户可使用 pip、uv、poetry 等包管理器安装。安装详情：https://cocoindex.io/docs/getting_started/installation

步骤 3：设置环境。先检查 COCOINDEX_DATABASE_URL 环境变量，若不存在使用默认值 postgres://cocoindex:cocoindex@localhost/cocoindex。需要 LLM API 的流程需询问使用哪家提供商（OpenAI、Anthropic、Gemini、Voyage、Ollama），并检查对应 API key。指南强调不要创建不含 LLM 的简化示例，应获取正确的 API key 并使用真实 LLM 函数。需创建 .env 文件并建立基础项目结构。

步骤 4：编写流程。流程结构包含：导入源数据、创建 collector、转换数据（遍历行）、导出到目标。关键原则：每个数据源在顶层数据作用域创建字段；使用 .row() 遍历表数据；务必将转换结果赋值给行字段（item["new_field"] = ...），而非局部变量；转换创建新字段而不改变现有数据；collector 可从任意作用域层级收集数据；导出必须在顶层进行。需避免的常见错误：使用局部变量存储转换结果；创建不必要的 dataclass 来镜像流程字段。

步骤 5：设计流程方案。当用户需求不匹配现有模式时，可组合多个模式的元素、参考更多示例（https://github.com/cocoindex-io/cocoindex?tab=readme-ov-file#-examples-and-demo）、从核心 API 出发思考、发挥创造力。常见起始模式包括：简单文本嵌入、代码嵌入与语言检测、基于 LLM 的提取到知识图谱、带刷新间隔的实时更新、自定义转换函数、可复用逻辑的转换流程、并发控制。

步骤 6：测试与运行。包括：cocoindex update --setup -f main；cocoindex server -ci main，然后在 https://cocoindex.io/cocoinsight 打开 CocoInsight。

四、数据类型

CocoIndex 拥有独立于编程语言的类型系统。自定义函数的返回值必须使用具体类型注解（这是类型推断的源头），参数注解可放宽；流程字段无需显式类型注解，CocoIndex 会自动推断。仅在实际使用时创建 dataclass/Pydantic 模型。常见类型类别：基本类型（str、int、float、bool、bytes、date、datetime、UUID）；向量类型（建议指定维度，如 cocoindex.Vector[cocoindex.Float32, Literal[768]]）；结构类型（dataclass、NamedTuple、Pydantic）；表类型（KTable、LTable）；Json 类型；Optional 类型。完整文档：https://cocoindex.io/docs/core/data_types

五、自定义函数

当需要自定义转换逻辑时创建自定义函数。简单转换、无需配置或初始化时使用独立函数；需要配置、初始化或复杂多步处理时使用 spec+executor。独立函数使用 @cocoindex.op.function() 装饰器，参数和返回值都需类型注解，可选 cache=True 和 behavior_version。Spec+Executor 需定义 FunctionSpec 配置类和 @cocoindex.op.executor_class(cache=True, behavior_version=1) 执行器类，执行器需包含 spec 属性，可选 prepare() 方法，必须实现 call()。缓存适用于 LLM API 调用、模型推理、外部 API 调用、计算昂贵操作。函数逻辑改变时需递增 behavior_version 以失效缓存。详细示例见 references/custom_functions.md，更多文档：https://cocoindex.io/docs/custom_ops/custom_functions

六、操作流程

CLI 操作：

• 设置流程：cocoindex setup main
• 一次性更新：cocoindex update main（可加 --setup 自动设置，--reset 强制重置）
• 实时更新：cocoindex update main.py -L（需在源上设置 refresh_interval 或源特定变更捕获）
• 删除流程：cocoindex drop main.py
• 检查流程：cocoindex show main.py:FlowName
• 无副作用测试：cocoindex evaluate main.py:FlowName --output-dir ./test_output

完整 CLI 参考见 references/cli_operations.md，文档：https://cocoindex.io/