最轻量可控路径是SentenceTransformers本地生成向量存入MongoDB Atlas，再用$vectorSearch查询；需确保向量维度、归一化、float32类型与索引严格一致，且$vectorSearch必须为聚合管道首阶段。
直接用 sentence-transformers 生成向量、存进 MongoDB Atlas 的向量索引，再用 $vectorSearch 查询——这是目前最轻量、最可控的路径。别被 LangChain 封装绕晕，先搞清底层数据流。
怎么把文本变成 MongoDB 能查的向量
嵌入模型输出必须是固定长度的一维 list[float]，且维度要和 Atlas 向量索引定义的 numDimensions 完全一致。常见坑是：用错模型（比如用了只支持单句的 all-MiniLM-L6-v2 去 encode 长段落）、没归一化（Atlas 默认用余弦相似度，输入向量最好单位化）、或 dtype 不匹配（MongoDB 只认 float32，Python list 默认是 float64）。
推荐做法：
- 用
SentenceTransformer加载开源模型，如"BAAI/bge-small-zh-v1.5"（中文友好）或"all-MiniLM-L6-v2"（通用快） - 调用
model.encode(text, normalize_embeddings=True)，显式开启归一化 - 转成 Python 原生 list：
vector.tolist()，避免 numpy array 直接入库（MongoDB 驱动不认） - 入库前检查长度：
len(vector) == 384（对应 BGE small）或384/768等，必须和 Atlas 索引配置一致
如何在 Atlas 中建能搜语义的向量索引
不是所有集群都默认开向量搜索，得手动建索引。关键点不在“怎么点控制台”，而在字段路径、距离算法、维度这三项必须和你写入的数据严格对齐。
立即学习“Python免费学习笔记（深入）”；
操作要点：
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 索引类型选
Vector Search，不是传统 text 或 2dsphere -
path填你存向量的字段名，比如"embedding"，不能带$或嵌套路径（如"meta.embedding"会失败） -
numDimensions必须等于你模型输出的向量长度，填错会导致查询返回空或报错"vector dimension mismatch" -
similarity推荐"cosine"（最常用），若用"euclidean"，入库前就得关掉normalize_embeddings - 建完等几分钟，状态变
READY才能查，别刚点完就跑代码
怎么用 PyMongo 发起语义搜索
不用 LangChain 的 MongoDBAtlasVectorSearch 类也能查，原生 aggregate() 更透明、更易调试。核心就是写对 $vectorSearch 阶段，其他都是常规管道。
关键结构：
- 第一阶段必须是
{"$vectorSearch": {...}}，且只能是 pipeline 第一个阶段（MongoDB 强制） -
queryVector是你要搜的问句向量，同样要normalize_embeddings=True，且长度/类型和索引一致 -
path和索引里定义的完全一样，大小写、下划线都不能错 -
limit控制返回几条，别设太大（>50 会明显拖慢），RAG 场景通常 3–5 条足够 - 后面可以跟
$project去掉_id或加score字段：{"score": {"$meta": "searchScore"}}
示例片段：
pipeline = [
{
"$vectorSearch": {
"index": "vector_index",
"path": "embedding",
"queryVector": query_vector,
"numCandidates": 100,
"limit": 5
}
},
{"$project": {"content": 1, "score": {"$meta": "searchScore"}}}
]
results = collection.aggregate(pipeline)
为什么本地 embed + Atlas search 比纯 API 调用更稳
用 OpenAI 的 text-embedding-3-small API 看似省事，但实际生产中容易卡在三处：网络抖动导致请求超时、配额突降中断批量入库、响应格式变更（比如某天突然多返回个 usage 字段）。而本地跑 sentence-transformers 模型，只要 GPU 显存够（BGE small 在 6G 卡上能跑 batch=16），整个流程就彻底脱离公网依赖。
但要注意：
- 模型加载一次后要复用
model实例，别每次查询都load，否则冷启动延迟秒级起步 - 长文本需分块（chunk），用
RecursiveCharacterTextSplitter或自己按标点切，别整篇喂给模型（会截断或崩） - Atlas 免费层（M0）不支持向量搜索，至少选 M2；并发高时注意
numCandidates和limit的组合对性能的影响
真正容易被忽略的是向量生命周期管理：入库的向量没更新机制，文档删了、改了，对应向量不会自动同步。要么定期全量重刷，要么在应用层维护 document_id → vector_id 映射做增量更新。
