使用LLM嵌入与元数据在Python中构建上下文感知搜索

当用户输入的内容与文档的字面表述不匹配时，传统的关键词搜索就会失效。例如，一位支持工程师搜索“登录一直失败”，却找不到标题为“OAuth2令牌刷新竞态条件”的工单，尽管这正是他们需要的。这正是上下文感知语义搜索要解决的核心问题。

语义搜索通过将文本转换为称为嵌入的稠密向量表示来解决这个问题，其中语义决定文本间的距离，而非精确的词匹配。在此基础上叠加结构化的元数据过滤（按日期、状态、团队、优先级），就得到了一个既理解用户意图又遵循上下文约束的系统。

本文全程演示了如何构建这样一个系统：从本地预训练模型生成嵌入、构建元数据感知的索引、余弦相似度排序，以及一个可在重启后持久化且无需重新编码的索引。

理解语义搜索的工作原理

句子嵌入模型将字符串转换为固定长度的浮点数向量。模型经过训练，使得语义相似的句子在高维空间中产生方向相近的向量。余弦相似度测量两个向量之间的夹角：cosine_similarity(A, B) = (A·B) / (||A|| ||B||)。当向量经过单位归一化后（即长度等于1.0），相似度简化为点积：A·B。分数范围从-1（相反）到1（相同）。实际上，不相关的文档得分通常在0.1–0.25之间，强匹配的得分高于0.6。

那么为什么元数据过滤很重要？嵌入模型编码的是语义内容，它们不编码文档的作者、所属团队或创建时间。这些属性存在于文本之外，必须单独处理。结合语义得分和元数据约束，才能使搜索在实际系统中变得有用。

数据集准备

我们使用20个工程支持工单，涵盖三个团队（基础设施、后端、前端）、四个优先级、两种状态以及两个月的时间窗口。每个工单是一个字典，text字段用于嵌入，其余字段用于过滤。

第一步：生成嵌入

使用all-MiniLM-L6-v2模型，将任意句子映射到384维向量。该模型完全在CPU上运行，从Hugging Face下载一次（约22MB）后本地缓存，无需API密钥。通过设置normalize_embeddings=True，每个输出向量的L2范数恰好为1.0，这样查询时余弦相似度简化为点积。

第二步：构建索引

索引存储嵌入矩阵及关联的元数据，并提供一个search方法，接受每个元数据字段的可选关键字参数。关键设计决策是先过滤后评分：后过滤会浪费点积计算，而先过滤确保min_score能丢弃不相关的结果。

第三步：运行查询

文章展示了三种查询：无过滤的纯语义搜索、按状态和日期过滤的搜索、跨团队按优先级过滤的搜索。例如，查询“资源耗尽和内存压力”并过滤状态为open、优先级为high，可以返回跨团队的相关工单。

通过本文，你将学会构建一个实用的上下文感知搜索系统，并能在自己的项目中应用。