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

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(nameTextEmbedding) def text_embedding_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope): data_scope[documents] flow_builder.add_source( cocoindex.sources.LocalFile(pathmarkdown_files)) doc_embeddings data_scope.add_collector() with data_scope[documents].row() as doc: doc[chunks] doc[content].transform( cocoindex.functions.SplitRecursively(), languagemarkdown, chunk_size2000, chunk_overlap500) with doc[chunks].row() as chunk: chunk[embedding] chunk[text].transform( cocoindex.functions.SentenceTransformerEmbed( modelsentence-transformers/all-MiniLM-L6-v2)) doc_embeddings.collect( filenamedoc[filename], locationchunk[location], textchunk[text], embeddingchunk[embedding]) doc_embeddings.export( doc_embeddings, cocoindex.storages.Postgres(), primary_key_fields[filename, location], vector_indexes[cocoindex.VectorIndexDef( field_nameembedding, metriccocoindex.VectorSimilarityMetric.COSINE_SIMILARITY)])这段代码声明的是结果形态不是执行顺序数据流动过程如下文件读入LocalFile(pathmarkdown_files)作为数据源每个文件成为documents中的一行。递归分块SplitRecursively按 Markdown 结构把长文切成 chunk文本片段chunk_size2000控制单块长度上限chunk_overlap500让相邻块保留重叠内容避免语义在块边界被截断。文本变向量SentenceTransformerEmbed加载all-MiniLM-L6-v2模型把每个 chunk 的text转成 embedding。写入 Postgres 并建向量索引collector 汇总各行后export到名为doc_embeddings的表以filenamelocation作主键同一文件的不同块各占一行并对embedding字段建余弦相似度的向量索引。注意这里没有出现任何哪些文件变了、哪些要重算的判断——那是引擎在运行期自动处理的。运行后如何核对索引结果把数据库地址告诉 CocoIndex然后触发更新export COCOINDEX_DATABASE_URLpostgresql://cocoindex:cocoindexlocalhost: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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考