问题：技术文档搜索，关键词匹配越来越不够用

去年我负责一个内部知识库项目，存了5000+篇技术文档。刚开始用Elasticsearch做全文搜索，用户反馈“搜不到想要的”，比如搜“怎么在Linux上装MySQL”，结果全是“Linux安装MySQL”这种字面匹配的文章。如果文章标题是“MySQL在CentOS部署指南”，只有包含“CentOS”才能排前面。用户经常需要换好几轮关键词。

正好公司开始推AI，我就评估了一下能不能用语义搜索替换。本文完整记录了从传统ES全文检索切换到AI语义搜索（Embedding+向量数据库+RAG）的实战过程，包括方案对比、代码实现、效果数据，以及遇到的坑。

方案一：传统Elasticsearch全文检索（BM25）

架构与实现

Elasticsearch版本8.11.0，索引使用standard分析器，查询用match和multi_match配合operator: "and"。

# Python 3.11 + elasticsearch-py 8.12.0
from elasticsearch import Elasticsearch
es = Elasticsearch("http://localhost:9200")

# 创建索引（使用标准分词）
index_mapping = {
    "mappings": {
        "properties": {
            "title": {"type": "text"},
            "content": {"type": "text"},
            "tags": {"type": "keyword"}
        }
    }
}
es.indices.create(index="knowledge_base", body=index_mapping)

# 索引文档（示例）
doc = {
    "title": "MySQL在CentOS部署指南",
    "content": "本文介绍如何在CentOS 7上通过Yum安装MySQL 8.0...",
    "tags": ["MySQL", "CentOS", "部署"]
}
es.index(index="knowledge_base", body=doc, id=1)

# 查询
def bm25_search(query):
    body = {
        "query": {
            "multi_match": {
                "query": query,
                "fields": ["title^3", "content", "tags"],
                "operator": "and"
            }
        },
        "size": 5
    }
    resp = es.search(index="knowledge_base", body=body)
    return [h["_source"] for h in resp["hits"]["hits"]]

用户输入“怎么在Linux上装MySQL”，实际分词后关键词“Linux”、“装”、“MySQL”，文档中必须同时出现这三个词（operator: and）。而我们的文档标题是“MySQL在CentOS部署指南”，没有“Linux”和“装”，所以排不到前面。即使文档内容里有“在Linux环境下...”，也因为分词粒度导致权重低。

调优尝试：同义词 & 自定义分词

我们试过添加同义词：“Linux=CentOS,Ubuntu,Debian”，“装=安装,部署”。效果有提升但维护困难，而且用户的口语化表述（“怎么”、“弄一下”）很难穷举。

// elasticsearch 同义词配置示例 (analysis/synonym.txt)
Linux,CentOS,Ubuntu,Debian
装,安装,部署
怎么,如何,怎样

配置后查询“怎么在Linux上装MySQL”能被翻译为“如何 在 Linux CentOS Ubuntu Debian 上 装 安装 部署 MySQL”，命中率提升10%，但仍然漏掉很多语义相关的文档（比如“MySQL服务启动教程”中没出现“装”）。

方案二：AI语义搜索（Embedding + 向量数据库 + RAG）

整体架构

我们选用OpenAI text-embedding-ada-002（2024年1月发布，1536维），向量数据库用Pinecone（免费层），RAG的生成模型用GPT-4。流程：

1. 离线：对所有文档分块，生成Embedding，存入Pinecone。
2. 在线：用户query → Embedding（相同模型）→ 向量检索 top-5 → 拼接上下文 → GPT-4生成答案。

代码实现：生成Embedding

# OpenAI Python 1.12.0
import openai
openai.api_key = "sk-xxxx"

def get_embedding(text: str, model="text-embedding-ada-002") -> list[float]:
    text = text.replace("\n", " ")
    resp = openai.Embedding.create(input=[text], model=model)
    return resp["data"][0]["embedding"]

# 预处理文档（分块）
import tiktoken  # tiktoken 0.6.0
encoder = tiktoken.encoding_for_model("gpt-4")

def chunk_text(text, max_tokens=500, overlap=50):
    tokens = encoder.encode(text)
    chunks = []
    start = 0
    while start < len(tokens):
        end = start + max_tokens
        chunk = tokens[start:end]
        chunks.append(encoder.decode(chunk))
        start = end - overlap
    return chunks

# 示例：将文档分块并生成embedding存入Pinecone
import pinecone  # pinecone 3.0.0
pinecone.init(api_key="pc-xxxx", environment="us-west1-gcp")
index = pinecone.Index("knowledge-base")

for doc_id, doc_text in enumerate(documents[:1000]):  # 先处理1000篇
    chunks = chunk_text(doc_text)
    for i, chunk in enumerate(chunks):
        vec = get_embedding(chunk)
        index.upsert([(f"{doc_id}_{i}", vec, {"doc_id": doc_id, "chunk_text": chunk})])

代码实现：在线检索与RAG

def semantic_search(query, top_k=5):
    query_vec = get_embedding(query)
    result = index.query(vector=query_vec, top_k=top_k, include_metadata=True)
    return [match["metadata"]["chunk_text"] for match in result["matches"]]

def rag_answer(query):
    context = "\n".join(semantic_search(query))
    prompt = f"基于以下上下文，用中文回答用户问题。如果上下文不够就回答“无法根据现有知识回答”。\n上下文：{context}\n用户问题：{query}\n回答："
    resp = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.2
    )
    return resp["choices"][0]["message"]["content"]

用户输入“怎么在Linux上装MySQL”，query Embedding会匹配到“MySQL在CentOS部署指南”（因为语义相近），还能匹配到“Linux环境下MySQL源码编译”等没有直接出现“装”字的文档。RAG阶段GPT-4会融合这些片段生成一个具体的步骤答案。

效果对比：准确率、召回率、延迟、成本

我们准备了一个测试集：50个用户真实提问，每个问题标注了正确答案对应的文档ID（允许多个，平均2.3个）。使用top-5命中作为“召回”，人工判断返回的内容是否能回答该问题作为“准确率”（答案是否正确）。

AI语义搜索在准确率和召回率上明显胜出，但延迟和成本剧增。对于知识库这种回答可以容忍几秒的场景，我们决定接受延迟，后续通过缓存、嵌入批量生成等优化。而传统搜索适合对实时性要求高、问题固定的场景（如电商商品搜索）。

避坑指南（5个实际踩过的坑）

坑1：Embedding模型不能直接复用开源版本

一开始用Sentence-BERT的all-MiniLM-L6-v2（384维）做离线embedding，但线上查询时用的同一个模型，结果向量相似度排序极差。原因：领域差异太大，我们知识库是技术文档，需微调或换更强的模型。后来换成OpenAI ada-002才有效果。如果不能用云API，至少要用BGE-large-zh等针对中文的模型。

坑2：分块策略不当导致上下文碎片

最早用固定500字符分块，结果一个完整的技术步骤被切到两个块里，RAG时GPT只看到碎片回答不出来。后来改用tiktoken按token数分（500 tokens），并加50 tokens重叠，解决了。

坑3：向量数据库中metadata字段大小限制

Pinecone免费层每个向量metadata最大40KB，而chunk_text可能超过，导致upsert失败。我们改为只存doc_id和chunk摘要，线下缓存完整文本，根据doc_id查询。

# 只存摘要
index.upsert([(f"{doc_id}_{i}", vec, {"doc_id": doc_id, "summary": chunk[:100]})])
# 检索后通过doc_id获取完整chunk
full_chunk = doc_chunks[doc_id][i]

坑4：GPT-4喜欢“自由发挥”，必须约束格式

最初prompt只写“根据上下文回答”，结果GPT-4会编造细节。后来加了“如果上下文不够就回答无法根据现有知识回答”，并用temperature=0.2。另外用function calling强制输出结构（如答案+置信度）效果更好。

坑5：缓存失效导致重复调用Embedding

每个query都实时生成embedding，一天就超OpenAI免费额度。做了两层缓存：同一query的embedding缓存到Redis（8小时过期）；热门query的结果缓存到MySQL（按小时更新）。成本降低80%。

import redis
r = redis.Redis()

def cached_embedding(query):
    key = f"emb:{hash(query)}"
    cache = r.get(key)
    if cache:
        return json.loads(cache)
    emb = get_embedding(query)
    r.setex(key, 28800, json.dumps(emb))
    return emb

总结（不废话）

传统ES全文检索适合精确匹配、低延迟、低成本的场景；AI语义搜索在理解意图和跨语言/术语泛化上碾压BM25，但代价是延迟和成本。我们最终采用混合架构：先用ES快速召回候选（依靠同义词），再用Embedding重排序，最后用GPT-4生成答案，取得了平衡（召回率91%，延迟1.2s，成本0.03美分/次）。

关键：别把AI当银弹，根据业务场景取舍。代码、测试集、配置都已放到GitHub（链接在评论），欢迎直接拿去用。