企业官网建设流程全解析

CocoIndex 向量索引教程：3 条命令把本地 Markdown 变成语义可检索的向量库

【免费下载链接】cocoindexIncremental engine for long horizon agents 🌟 Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex

本教程用 CocoIndex（开源数据索引引擎）完成一件事：读入一批本地 Markdown 文档，拆分后转换为 embedding（表示文本语义的数值向量），写入 PostgreSQL，形成可按语义相似度检索的向量索引。全程只需要一段 Python 定义和三条命令，跑完即可在数据库里查到向量数据。

先说清楚最终产物

目标很具体：目录里放着一堆.md文件，跑完后 PostgreSQL 里出现一张向量表，每行对应文档里的一个文本片段及其 embedding。之后你可以用任意查询向量和表中向量做余弦相似度比较，实现"按语义找文档"，而不是按关键词匹配。

CocoIndex 在这个过程中的角色，如下图所示：源数据经过自定义转换（LLM 推理、结构化抽取、向量嵌入都在其能力范围内），由引擎增量地同步到目标存储。

一分钟看懂 CocoIndex 是什么

CocoIndex 是一个支持自定义转换逻辑和增量更新的数据索引引擎。你用普通 Python 声明"目标状态 = 转换函数(源数据)"，引擎负责检测哪些数据变了，只重算变化的部分。

• 增量是内建的：源文件新增、修改、删除后重跑，未变化的数据不会重新计算。
• 转换逻辑自由：分块、嵌入、调用 LLM 都是你在 Python 里写的函数，不需要新 DSL。
• 面向典型检索场景：文本语义检索、图片索引、知识图谱构建都可以基于同一套模型搭。

本教程只做文本检索这一种场景。

最小化环境安装命令

环境一次装齐：安装引擎、起一个带 pgvector 扩展的 PostgreSQL、准备好输入目录。

pip install -U 'cocoindex[embeddings]' docker compose up -d # 使用仓库自带的 dev/postgres.yaml，端口 5432 mkdir cocoindex-quickstart && cd cocoindex-quickstart mkdir markdown_files

为什么需要它：

• pip install -U 'cocoindex[embeddings]'：装上引擎本体和嵌入模型依赖，后面cocoindex update命令就来自这里。
• Docker Compose 起的 PostgreSQL 是向量的落盘位置，同时是 CocoIndex 记录增量状态的地方；dev/postgres.yaml 使用pgvector/pgvector:pg17镜像，账号、密码、库名都是cocoindex。
• markdown_files/是输入目录，样例数据可以直接从仓库里的 docs/src/content/docs/getting_started/markdown_files.zip 下载解压进去，共 3 个 Markdown 文件。

flow 代码逐段讲清数据流向

数据在 CocoIndex 里以"流"（flow，即数据从源到目标的管道）的形式流动。下面这份main.py就是整条管道的完整定义，数据依次经过四个环节。

import 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: 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"]) doc_embeddings.export( "doc_embeddings", cocoindex.storages.Postgres(), primary_key_fields=["filename", "location"], vector_indexes=[cocoindex.VectorIndexDef( field_name="embedding", metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY)])

这段代码声明的是结果形态，不是执行顺序，数据流动过程如下：

1. 文件读入：LocalFile(path="markdown_files")作为数据源，每个文件成为documents中的一行。
2. 递归分块：SplitRecursively按 Markdown 结构把长文切成 chunk（文本片段），chunk_size=2000控制单块长度上限，chunk_overlap=500让相邻块保留重叠内容，避免语义在块边界被截断。
3. 文本变向量：SentenceTransformerEmbed加载all-MiniLM-L6-v2模型，把每个 chunk 的text转成 embedding。
4. 写入 Postgres 并建向量索引：collector 汇总各行后export到名为doc_embeddings的表，以filename+location作主键（同一文件的不同块各占一行），并对embedding字段建余弦相似度的向量索引。

注意这里没有出现任何"哪些文件变了、哪些要重算"的判断——那是引擎在运行期自动处理的。

运行后如何核对索引结果

把数据库地址告诉 CocoIndex，然后触发更新：

export COCOINDEX_DATABASE_URL="postgresql://cocoindex:cocoindex@localhost:5432/cocoindex" cocoindex update main

跑完后终端会打印统计行，样例数据的预期输出是documents: 3 added, 0 removed, 0 updated。三个数字分别代表源目录里新增、删除、内容变化的文档数：added说明 3 个文件首次入库并完成了分块和嵌入；removed和updated为 0 说明没有旧数据需要清理或重算。此时去 PostgreSQL 查doc_embeddings表，能看到每个块对应的text与embedding列，向量索引也已建好。

想验证增量行为，改动markdown_files/里的一个文件再跑一次同一条命令，输出会只剩该文件的1 updated，其余文档不会重新计算。

接下来可以往哪走

• 读核心概念文档，理解源状态、目标状态与记忆化这套心智模型。
• 浏览示例目录，里面有 PDF 转 Markdown、图片语义检索（下图这类图片可以直接作为数据源建索引）、知识图谱等更完整的案例。

• 把LocalFile换成其他数据源（如对象存储、Kafka），把Postgres换成 Qdrant 等向量库，管道结构不变。

到此，向量库已经可用：后续任何查询都可以转成向量后直接在doc_embeddings表上做相似度检索。

【免费下载链接】cocoindexIncremental engine for long horizon agents 🌟 Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex