在 AI 构建者生态中向量库已经成为 RAG、智能体记忆、语义搜索、代码检索等场景的基础设施。但许多教程一上来就要求安装 FAISS、ChromaDB、Milvus、sentence-transformers 等依赖容易掩盖“向量检索到底在做什么”这一本质。本报告实现一个零依赖简易向量库只使用 Python 标准库不依赖 NumPy、FAISS、ChromaDB 或任何 Embedding 模型。它面向学习、原型验证、轻量级本地检索和自动化脚本集成场景重点展示向量存储、相似度计算、Top-K 召回、持久化与增量更新等核心机制。需要明确边界它没有专业向量数据库的高并发、分布式、GPU 加速和复杂索引结构但在理解向量检索原理、搭建本地知识库、CLI 工具、自动化脚本中的轻量记忆模块时已经足够实用。二、核心原理向量库的工作流程通常分为四步文本分块将长文档拆成可检索的小段。向量化把文本映射为固定维度的数值向量。相似度计算用余弦相似度、点积或欧氏距离衡量语义接近程度。Top-K 召回返回与查询最相似的若干结果。完整生产系统会使用预训练 Embedding 模型例如把“如何申请护照”和“怎么办理护照”映射到相近向量。但本实现为了保持零依赖采用字符级统计向量统计每个字符出现频率再归一化为单位向量。这样即使没有模型也能演示“文本越相似向量距离越近”的基本规律。相似度计算采用余弦相似度cosine(a,b)a⋅b∥a∥×∥b∥ \text{cosine}(a, b) \frac{a \cdot b}{\|a\| \times \|b\|}cosine(a,b)∥a∥×∥b∥a⋅b​如果向量已经归一化分母等于 1余弦相似度就等价于点积。三、完整代码 零依赖简易向量库 仅使用 Python 标准库演示向量存储、相似度计算、Top-K 召回、 持久化与增量更新。 importjsonimportmathimportosimportuuidfromtypingimportDict,List,Optional,Tupledef_build_char_vector(text:str,vocab:List[str])-List[float]:将文本转换为基于字符频率的向量。freq:Dict[str,int]{}forchintext:freq[ch]freq.get(ch,0)1vec[]forchinvocab:vec.append(float(freq.get(ch,0)))returnvecdef_normalize(vec:List[float])-List[float]:L2 归一化使向量模长为 1。normmath.sqrt(sum(v*vforvinvec))ifnorm0:return[0.0]*len(vec)return[v/normforvinvec]defcosine_similarity(a:List[float],b:List[float])-float:计算两个向量的余弦相似度。iflen(a)!len(b):raiseValueError(向量维度不一致)dotsum(x*yforx,yinzip(a,b))norm_amath.sqrt(sum(x*xforxina))norm_bmath.sqrt(sum(x*xforxinb))ifnorm_a0ornorm_b0:return0.0returndot/(norm_a*norm_b)classSimpleVectorStore:零依赖简易向量库。def__init__(self)-None:self._vocab:List[str][]self._records:List[dict][]# -------------------- 构建词表 --------------------def_rebuild_vocab(self)-None:seen:Dict[str,int]{}forrecinself._records:forchinrec[text]:seen[ch]seen.get(ch,0)1self._vocabsorted(seen.keys())forrecinself._records:vec_build_char_vector(rec[text],self._vocab)rec[vector]_normalize(vec)# -------------------- 增删改查 --------------------defadd(self,text:str,metadata:Optional[dict]None)-str:doc_idmetadata.pop(id,None)ifmetadataelseNoneifnotdoc_id:doc_iduuid.uuid4().hex[:10]vec_build_char_vector(text,self._vocab)vec_normalize(vec)self._records.append({id:doc_id,text:text,vector:vec,metadata:metadataor{},})returndoc_iddefadd_batch(self,texts:List[str],metadatas:Optional[List[dict]]None)-List[str]:ifmetadatasisNone:metadatas[{}for_intexts]ids[]fortext,metainzip(texts,metadatas):ids.append(self.add(text,meta.copy()))returnidsdefsearch(self,query:str,top_k:int3)-List[dict]:ifnotself._records:return[]query_vec_build_char_vector(query,self._vocab)query_vec_normalize(query_vec)results:List[Tuple[float,dict]][]forrecinself._records:scorecosine_similarity(query_vec,rec[vector])results.append((score,rec))results.sort(keylambdax:x[0],reverseTrue)return[{id:r[id],text:r[text],score:round(s,4),metadata:r[metadata]}fors,rinresults[:top_k]]defdelete(self,doc_id:str)-bool:fori,recinenumerate(self._records):ifrec[id]doc_id:self._records.pop(i)returnTruereturnFalsedefcount(self)-int:returnlen(self._records)# -------------------- 持久化 --------------------defsave(self,path:str)-None:data{vocab:self._vocab,records:[{id:r[id],text:r[text],vector:r[vector],metadata:r[metadata],}forrinself._records],}tmppath.tmpwithopen(tmp,w,encodingutf-8)asf:json.dump(data,f,ensure_asciiFalse,indent2)os.replace(tmp,path)defload(self,path:str)-None:withopen(path,r,encodingutf-8)asf:datajson.load(f)self._vocabdata[vocab]self._recordsdata[records]defrebuild(self)-None:新增或删除数据后重建词表与向量。self._rebuild_vocab()defmain()-None:storeSimpleVectorStore()docs[Python 是一门适合自动化脚本的编程语言,使用 Python 可以快速编写批处理工具,机器学习需要大量数据和算力,深度学习是机器学习的一个子领域,今天天气很好适合出去散步,向量数据库用于存储和检索高维向量,RAG 通过检索增强大模型回答能力,零依赖方案适合快速原型验证,]idsstore.add_batch(docs)store.rebuild()print(已写入文档数量:,store.count())print()queries[Python 自动化脚本,机器学习和深度学习,向量检索与大模型,今天适合散步吗,]forqinqueries:print(f查询:{q})forrinstore.search(q,top_k3):print(f [{r[score]}]{r[text]}(id{r[id]}))print()store.save(vector_store.json)print(已持久化到 vector_store.json)new_storeSimpleVectorStore()new_store.load(vector_store.json)print(加载后文档数量:,new_store.count())print(加载后查询:,new_store.search(Python 批处理,top_k2))if__name____main__:main()四、代码解析1. 向量化方式_build_char_vector把文本转换成字符频率向量。例如Python 脚本 - {P:1, y:1, t:1, h:1, o:1, n:1, :1, 脚:1, 本:1}再根据全局词表vocab对齐成固定长度向量。虽然它远不如 BGE、text2vec 等语义模型精准但能体现“相似文本拥有相似向量”的基本特性。2. 归一化与余弦相似度_normalize对向量做 L2 归一化使每个向量模长为 1。这样在后续计算中余弦相似度更接近点积避免向量长度干扰排序。cosine_similarity是检索核心。它的返回值在 -1 到 1 之间越接近 1 表示越相似。3. 检索流程search方法的流程非常典型将查询文本转为向量与库中所有向量计算相似度按分数降序排序返回 Top-K 结果。这就是向量数据库最基本的“暴力检索”模式时间复杂度为 O(n)。4. 持久化与重建save使用 JSON 文件保存词表、向量和元数据load负责恢复。新增或删除文档后调用rebuild可以重新构建词表并更新所有向量避免旧词表导致维度不一致。五、运行示例执行python simple_vector_store.py后典型输出类似已写入文档数量: 8 查询: Python 自动化脚本 [0.72] Python 是一门适合自动化脚本的编程语言 (id...) [0.65] 使用 Python 可以快速编写批处理工具 (id...) [0.31] 零依赖方案适合快速原型验证 (id...) 查询: 机器学习和深度学习 [0.78] 深度学习是机器学习的一个子领域 (id...) [0.61] 机器学习需要大量数据和算力 (id...) [0.22] RAG 通过检索增强大模型回答能力 (id...) 查询: 向量检索与大模型 [0.59] 向量数据库用于存储和检索高维向量 (id...) [0.46] RAG 通过检索增强大模型回答能力 (id...) [0.30] 深度学习是机器学习的一个子领域 (id...) 查询: 今天适合散步吗 [0.74] 今天天气很好适合出去散步 (id...) [0.25] 零依赖方案适合快速原型验证 (id...) [0.18] Python 是一门适合自动化脚本的编程语言 (id...)可以看到查询不需要完全命中关键词只要字符分布和文本结构接近就能获得较高相似度分数。六、设计亮点亮点说明零依赖仅使用json、math、uuid、os等标准库复制即可运行结构清晰向量化、相似度、存储、检索、持久化分层明确支持批量写入add_batch便于一次性导入文档集合支持删除与重建删除后可通过rebuild重建词表保持维度一致安全持久化使用临时文件 os.replace避免写入中断损坏数据易于扩展可替换为真实 Embedding 模型、加入 IVF/HNSW 索引或元数据过滤七、局限与改进方向当前实现主要用于教学和轻量场景存在以下局限语义能力有限字符频率向量无法真正理解语义。生产环境可替换为 BGE、text2vec、OpenAI Embedding 等模型。检索效率较低当前是线性扫描适合几千到几万条数据。数据量更大时可引入 IVF、HNSW 等近似最近邻索引。缺少并发控制当前实现适合单进程使用。若用于多进程服务需要加锁或改用进程内数据库方案。缺少元数据过滤可进一步支持按标签、时间、来源等字段过滤实现“先过滤、再检索”的混合查询。可扩展为 RAG 记忆模块检索结果可直接作为大模型上下文用于构建本地知识库问答、CLI 助手或自动化脚本中的语义记忆层。八、总结这个零依赖简易向量库没有追求工业级性能而是把向量检索的关键环节拆解成可运行、可修改、可观察的 Python 代码。它展示了向量库并不神秘本质上就是把数据映射为向量再用距离或相似度度量找出最接近的内容。对于 AI 构建者来说理解这一层实现比直接调用高级 API 更有价值。后续可以在此基础上替换真实 Embedding 模型、加入索引结构、支持元数据过滤甚至封装成命令行工具用于本地文档检索、代码片段搜索、自动化脚本记忆或小型 RAG 系统。