前言

最近挺多球友对Python版本的企业智能知识库系统挺感兴趣的,有些球友要用这个项目去面试。

接下来,给大家解析一下这个项目用到的技术亮点,希望对你会有所帮助。

一、为什么要有 Python 后端

企业智能知识库的第一版后端是 Java Spring Cloud 微服务架构,AI 侧通过 LangChain4j 编排模型、文档切分和检索增强生成。

为了验证技术方案的通用性、降低 AI 模块的实验成本,我们又实现了一套 FastAPI + Python 3.12 后端,与 Java 端的接口、数据库结构、检索参数一一对应。

两套后端不是简单的"翻译",而是各有分工:

维度Java 后端Python 后端
定位生产级微服务,9 个独立服务模块化单体,一个进程承载全部业务域
Web 框架Spring Boot 3.2FastAPI(ASGI)
数据库访问MyBatis Plus + 手写 XMLSQLAlchemy 2.0 Async + Alembic
AI 编排LangChain4jLangChain(Python)
检索存储Elasticsearch dense\_vectorElasticsearch Async Client
异步任务RabbitMQ + CompletableFutureRabbitMQ + Celery
流式输出SSESSE(异步生成器)
响应模型Lombok + JacksonPydantic v2
一句话总结双后端策略:Java 验证"企业级工程化",Python 验证"AI 快速迭代"。业务接口两边保持同一套语义,谁更适合落地谁就上生产。

二、LangChain 在项目里的真实落点

很多教程喜欢"为了用而用"地把整条 RAG 流水线都塞进 LangChain,但本项目只引用了真正有增量价值的组件。查看 pyproject.toml:

langchain-text-splitters>=0.2      # 文档智能分块(已实际使用)
langchain-community>=0.2           # 社区集成(预留)
langchain-openai>=0.1              # OpenAI 兼容模型接入(预留)

实际代码中,LangChain 的 RecursiveCharacterTextSplitter 承担了 RAG 的第一环——中文文档智能分块,其余环节(Embedding、向量检索、关键词检索、RRF 融合、LLM 重排、对话补全)由 async 原生客户端直连实现,理由见第七章《选型哲学》。

2.1 Python RAG 子系统结构

apps/ai/rag/
├── chunking_service.py      # ★ LangChain 文本分块(本节主角)
├── embedding_service.py     # 向量嵌入 + Redis 缓存 + 批量 + 降级
├── vector_index_service.py  # ES 索引管理 / kNN 向量检索 / BM25 关键词检索
├── rag_retrieval_service.py # 混合检索编排:kNN + BM25 → RRF → LLM 重排
├── rag_chat_service.py      # RAG 对话:Prompt 构建 / 记忆 / 引用 / SSE
├── models.py                # DocumentChunk / SearchResult / RAGResponse
└── routers/                 # FastAPI 路由层

2.2 核心分块代码

chunking_service.py 只做了三件事:**配置分割器 → 切文本 → 包一层带元数据的 **DocumentChunk。

from langchain_text_splitters import RecursiveCharacterTextSplitter

def _get_splitter(chunk_size: int = 512, overlap: int = 64):
    """按优先级依次尝试以下分隔符:
    \n\n(段落) -> \n(换行) -> 。(中文句号) -> .(英文句号)
    -> ;(中文分号) -> ; -> ,(中文逗号) -> , -> 空格 -> 单字符
    """
    return RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=overlap,
        separators=["\n\n", "\n", "。", ".", ";", ";", ",", ",", " ", ""],
        length_function=len,
        is_separator_regex=False,
    )

chunk_text 负责真正的切分,并过滤掉空白块:

def chunk_text(text: str, chunk_size: int = 512, overlap: int = 64) -> List[str]:
    if not text or not text.strip():
        return []

    splitter = _get_splitter(chunk_size, overlap)
    chunks = splitter.split_text(text)

    result = [chunk.strip() for chunk in chunks if chunk.strip()]
    logger.debug(
        f"文本分块完成: 原文本长度={len(text)}, 分块数={len(result)}, "
        f"块大小={chunk_size}, 重叠={overlap}"
    )
    return result

chunk_document 则在每个块上附加文档级上下文(标题、章节、分块序号、总块数),这是检索结果"自包含"的关键:

def chunk_document(doc_id, content, chunk_size=512, overlap=64, extra_metadata=None):
    chunks = chunk_text(content, chunk_size, overlap)
    metadata = extra_metadata or {}

    document_title = metadata.pop("document_title", None)
    heading = metadata.pop("heading", None)
    publish_time = metadata.pop("publish_time", None)

    document_chunks = []
    for i, chunk_content in enumerate(chunks):
        chunk = DocumentChunk(
            doc_id=doc_id,
            chunk_id=f"{doc_id}_chunk_{i}",
            content=chunk_content,
            document_title=document_title,
            heading=heading,
            publish_time=publish_time,
            metadata={
                "doc_id": doc_id,
                "chunk_index": i,
                "total_chunks": len(chunks),
                "char_count": len(chunk_content),
                **metadata,
            },
        )
        document_chunks.append(chunk)
    return document_chunks

DocumentChunk 用 dataclass 建模(分块数据存在 ES,不落 MySQL),并内置 to_es_doc() 把对象转成 ES 文档:

@dataclass
class DocumentChunk:
    doc_id: int
    chunk_id: str                 # 唯一标识: "{doc_id}_chunk_{index}"
    content: str
    embedding: Optional[List[float]] = None    # 1024 维向量
    metadata: Dict[str, Any] = field(default_factory=dict)
    document_title: Optional[str] = None
    heading: Optional[str] = None
    publish_time: Optional[str] = None

    def to_es_doc(self) -> Dict[str, Any]:
        doc = {
            "doc_id": self.doc_id,
            "document_id": self.doc_id,
            "chunk_id": self.chunk_id,
            "content": self.content,
            "embedding": self.embedding,
            "metadata": self.metadata,
        }
        if self.document_title:
            doc["document_title"] = self.document_title
        if self.heading:
            doc["heading"] = self.heading
        if self.publish_time:
            doc["publish_time"] = self.publish_time
        return doc

三、LangChain 切分器凭什么"智能":递归分块原理

RecursiveCharacterTextSplitter 不是"数到 512 个字符就一刀切",而是一个递归降级的分隔符栈:它拿着有序分隔符列表,从最"大"的语义边界(段落)开始尝试切分;如果某一块仍然超过阈值,就用下一个更小的分隔符继续切,直到最小粒度(单字符)兜底。

图片.png

这套机制对中文尤其友好,因为中文的语义边界是"段落 > 句子 > 分句"而不是字符。

如果把分隔符列表顺序写反——先按逗号切,会把本来完整的一句话拆得稀碎,嵌入向量质量断崖式下跌。

3.1 中文分隔符的排序为什么重要

优先级分隔符语义粒度实际效果
1\n\n段落尊重 Markdown/自然段边界
2\n换行代码块、列表项不被打散
3。中文句号中文句级切分
4.英文句号兼容英文/代码文档
5; ;分号长句内的并列分句
6, ,逗号实在超长时的次优边界
7空格单词边界兜底
8空字符串单字符最终保底,保证不超上限

3.2 重叠(overlap)解决了什么问题

一个完整的论点经常横跨两个块的切分点。如果没有重叠,第 N 块的向量"缺下半句",第 N+1 块"缺上半句",两边都不完整,检索召回和 LLM 理解都会打折。chunk_overlap=64 让相邻块共享边界上下文,用约 12.5% 的存储冗余换回明显的召回收益——这个比例正是业界推荐的 10%–20% 区间。

工程细节:LangChain 的 RecursiveCharacterTextSplitter 默认 length_function=len,即按字符数而非 token 数计算块大小。本项目 512/64 是字符口径,与 Java 版"512 token ≈ 1024 字符 + 128 字符重叠"处于同一量级;若要严格按 token 切分,可替换为 TokenTextSplitter 并接入分词器,这就是下一阶段的优化点。

四、从"切好的块"到"可检索的向量":Embedding 与索引

分块只是 RAG 的第一环,接下来经历 chunk → embedding → ES 三步:

图片.png

4.1 Embedding 的三个工程化设计

  1. Redis 缓存命中优先:缓存 Key 为 rag:emb: + 文本 MD5,TTL 24 小时。同一份文档反复入库、增量更新时相同块直接命中,批量场景可省掉大量 API 费用。
def _build_cache_key(text: str) -> str:
    return "rag:emb:" + hashlib.md5(text.encode("utf-8")).hexdigest()

async def _embed(text: str) -> List[float]:
    if not text:
        return _zero_vector()
    client, _ = await _get_embedding_client()
    if client is None:
        return _zero_vector()

    cache_key = _build_cache_key(text)
    cached = await _cache_get(cache_key)
    if cached is not None:
        return cached

    try:
        vector = await _call_embed_api(text)
        await _cache_set(cache_key, vector)
        return vector
    except Exception as e:
        logger.error("单条嵌入失败: {}", e)
        return _zero_vector()
  1. 零向量兜底而不是抛异常:Embedding 失败返回 1024 维全零向量,后续混合检索发现向量不可信时自动退化为纯 BM25,而不是让整条链路报 500。
  2. Redis 是可选依赖:RedisManager 获取失败就跳过缓存,符合 Java 端 @Autowired(required=false) 的"缓存坏了不拖垮主流程"思想。

4.2 ES 索引设计

ES 索引 kb_ai_chunks 的关键 mapping:

{
  "mappings": {
    "properties": {
      "chunk_id":    {"type": "keyword"},
      "content":     {"type": "text"},
      "embedding":   {"type": "dense_vector", "dims": 1024, "index": true, "similarity": "cosine"},
      "document_title": {"type": "text", "fields": {"keyword": {"type": "keyword", "ignore_above": 256}}},
      "heading":     {"type": "keyword"},
      "doc_id":      {"type": "long"},
      "metadata":    {"type": "object"}
    }
  }
}

content 走 text(支持 BM25 全文检索),embedding 走 dense\_vector(支持 kNN 语义检索),同一份块同时服务两种检索,这正是混合检索的地基。

五、在线问答:混合检索 → RRF 融合 → LLM 重排 → 生成

5.1 一次 RAG 问答的完整旅程

图片.png

5.2 混合检索与 RRF 融合

向量检索能理解"同义词/语义相近",BM25 擅长"精确术语命中",两者互为补充。

Python 侧对每个榜单算倒数排名融合分:

RRF_score(d) = vec_weight / (k + rank_vec(d)) + kw_weight / (k + rank_kw(d))
def _rrf_fusion(vec_results, kw_results, k=60, vec_weight=0.5, kw_weight=0.5):
    scores = {}
    for rank, item in enumerate(vec_results):
        cid = item.get("chunk_id")
        if cid not in scores:
            scores[cid] = {**item, "rrf_score": 0.0}
        scores[cid]["rrf_score"] += vec_weight / (k + rank + 1)
        scores[cid]["vec_rank"] = rank + 1
        scores[cid]["vector_score"] = float(item.get("score", 0))

    for rank, item in enumerate(kw_results):
        cid = item.get("chunk_id")
        if cid not in scores:
            scores[cid] = {**item, "rrf_score": 0.0}
        scores[cid]["rrf_score"] += kw_weight / (k + rank + 1)
        scores[cid]["kw_rank"] = rank + 1
        scores[cid]["bm25_score"] = float(item.get("score", 0))

    merged = sorted(scores.values(), key=lambda x: x["rrf_score"], reverse=True)
    return merged

工程细节:

  • 融合时只依赖排名,不依赖原始分数,规避了 BM25 与 cosine 得分量纲不一致的问题;
  • 每条结果同时保留 bm25_score / vector_score / vec_rank / kw_rank,方便日志排查和效果调优;
  • hybrid_search() 里语义权重默认 0.6、关键词 0.4(语义优先),而 _rrf_fusion 的可调参数让 A/B 实验不用改代码。

5.3 为什么不直接信任 RRF 的 Top-5

RRF 的排序是"关键词+语义"层面的,不一定"对回答问题最有帮助"。混合检索返回的候选会先经过一道 LLM 重排质检:用"搜索相关性评估专家"Prompt 让大模型对每个候选打 1–10 分,过滤低分块后只把高相关块送进生成阶段。

async def _rerank_with_llm(candidates, query, top_k):
    client, model = await AiChatService._get_llm_client("qwen")
    scored = []
    for candidate in candidates:
        prompt = _build_rerank_prompt(query, candidate.get("content", ""))
        response = await client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            temperature=0,          # 评分要稳定,不开创造
            max_tokens=10,          # 只返回一个整数
        )
        score = _parse_rerank_score(response.choices[0].message.content or "")
        scored.append((candidate, score))
    scored.sort(key=lambda x: x[1], reverse=True)
    return [item for item, _ in scored[:top_k]]

重排 Prompt 写明了评分语义:"10 – 直接完美回答 / 7-9 – 高度相关 / 4-6 – 部分相关 / 1-3 – 基本无关";解析用 \b([1-9]|10)\b 正则,抽不出数字就回退为 5,防止一次打分异常拖垮整条链路。

5.4 Prompt 注入与防幻觉

Python 侧与 Java 保持同一套 Prompt 模板(=== 参考资料 === + === 用户问题 ===),核心约束只有一句话:参考资料没有的内容就明说答不了,绝不编造:

RAG_SYSTEM_PROMPT = """你是一个企业知识库助手。请仅根据以下参考资料回答用户的问题。
如果参考资料中没有相关信息,请说明【根据现有知识库暂时无法回答此问题】,绝对不要编造内容。
回答时,请在引用资料处的末尾标注引用编号,如 [1]、[2]。
回答应当专业、准确、简洁。"""

每个检索块会带上 来源文档 + 章节,LLM 被要求按 [1][2] 标注出处,回答后前端渲染引用面板,实现"有据可查"。

5.5 SSE 流式输出的两个细节

  1. 换行不能被吞:SSE 协议以换行分隔事件,模型吐出的正文里若含 \n,直接拼进 data: 会破坏事件流,所以要先转义:
escaped = delta.content.replace("\n", "\ndata: ")
yield f"event: message\ndata: {escaped}\n\n"
  1. 雪花 ID 必须转字符串:Java 端 Snowflake ID 超过 JS Number.MAX_SAFE_INTEGER,直接进 JSON 会丢精度,done 事件统一把 ID 转 str:
done_data = json.dumps({
    "conversationId": str(conversation_id),
    "messageId": str(ai_message_id),
    ...
}, ensure_ascii=False)
yield f"event: done\ndata: {done_data}\n\n"

六、重建索引:单文档同步链路 + Celery 异步化预留

apps/ai/rag/routers/rag_reindex_router.py 提供了完整可用的重建索引接口,当前实现为单文档同步链路(删除旧索引 → LangChain 分块 → Embedding → ES 批量写入),接口直接返回 chunks_created / chunks_indexed 统计:

图片.png

这个接口有三个值得注意的设计点:

  1. 删除后重建,天然幂等:先 delete_document_chunks(doc_id) 清掉旧分块再写入,同一文档重复重建不会产生"幽灵旧块";
  2. 参数可调且带校验:chunk_size=512 (ge=128, le=4096)、overlap=64 (ge=0, le=512) 作为 Query 参数开放,方便针对不同文档类型做分块参数实验;
  3. 顶层元数据对齐 ES 字段:document_title / publish_time 走 ES top-level 字段而不是塞进 metadata,与 Java 版索引结构一致,前端检索结果格式化零成本。
@router.post("/{doc_id}")
async def reindex_document(
    doc_id: int,
    content: str = Query(..., description="要索引的文档内容"),
    chunk_size: int = Query(512, ge=128, le=4096),
    overlap: int = Query(64, ge=0, le=512),
    document_title: Optional[str] = Query(None),
    ...
):
    deleted = await delete_document_chunks(doc_id)          # 1. 幂等清理
    chunks = chunk_document(doc_id, content, chunk_size, overlap,
                            extra_metadata=metadata or None)  # 2. LangChain 分块
    embeddings = await embed_texts([c.content for c in chunks])  # 3. 批量向量化
    for chunk, embedding in zip(chunks, embeddings):
        chunk.embedding = embedding
    indexed = await index_chunks(chunks)                    # 4. ES bulk 写入
    return Result.success(data={
        "chunks_created": len(chunks),
        "chunks_indexed": indexed,
    }).model_dump()

6.1 Celery:全量重建的异步化方向(已配置、待接线)

单文档同步重建对单篇文档完全够用;但"全量重建几万篇文档"不能塞在一个 HTTP 请求里。项目的处理是先把基础设施备好、代码留好挂载点:

# config.py — Celery Broker / Backend 已配置(Redis 3 号库)
celery_broker_url: str = "redis://:susan123@117.72.88.11:6379/3"
celery_result_backend: str = "redis://:susan123@117.72.88.11:6379/3"
# rag_reindex_router.reindex_all — 当前返回"已提交"确认
# 注释已明确生产路径:此操作触发后台 Celery 异步任务,遍历文档重新索引
return Result.success(data={
    "message": "全量重建索引已提交",
    "current_stats": stats,
}).model_dump()

未来的接线方式(也是面试时可以展开的演进方案):

图片.png

设计要点:Celery 自带 ack + 重试(分块/向量化失败不丢任务)、Worker 数量可随吞吐独立扩容;Java 端对应的异步消费由 RabbitMQ ReindexConsumer 承担——两套后端都保留了"单篇可同步、全量可异步"的伸缩路径,这正是架构演进时最舒服的状态:先跑通正确性,再把耗时路径搬进队列。

七、LangChain 选型哲学:不"为用而用"

这是本文最想传达的工程判断。LangChain 的价值是抽象层与生态,但它也带来黑盒、升级破坏、调试困难等成本。本项目的取舍是:

LangChain 能力本项目是否采用原因
RecursiveCharacterTextSplitter✅ 实际使用分块质量直接决定 RAG 上限,LangChain 的递归切分成熟、可配分隔符,性价比最高
langchain-openai ChatOpenAI⚠️ 预留,未直接使用对话走 AsyncOpenAI 原生客户端:全异步、SSE 逐 token 更可控、prompt 组装只有几十行,不需要框架包装
langchain-community⚠️ 预留若后续要接 Chroma/FAISS 等本地向量库,可直接复用社区封装
LangChain LCEL 链式编排❌ 未使用本项目检索/重排/生成顺序固定且需要精细的异常分支,原生代码可读性更好
内置向量库 VectorStore❌ 未使用生产环境需要 ES 的 BM25 + dense\_vector 混检,向量库由 ES 承担

结论一句话:把 LangChain 当"工具箱"而不是"框架"——能显著提效的组件(分块器)直接采用,其余环节保留原生控制力。这既拿到了生态红利,又不被框架绑架,是团队在 Java 与 Python 两套后端沉淀出的统一经验。


八、常见面试题(Python + LangChain 视角)

Q1 LangChain 的 RecursiveCharacterTextSplitter 和固定长度切分有什么区别?

固定长度切分在字符中间硬切,中文语义会被从中间截断;递归切分维护一个"段落 → 换行 → 句号 → 分号 → 逗号 → 空格"的分隔符栈,优先在完整语义边界切分,超长时才逐步降级到更细的分隔符,最后才用单字符兜底。叠加重叠窗口,边界语义不丢失。

Q2 chunk\_size 和 chunk\_overlap 是怎么定的?

取决于"语义完整"与"检索精度"的平衡:块太小,语义单元装不下、向量被稀释;块太大,一个向量混合多个主题、检索精度下降。项目取 512 + 64 重叠(约 12.5% 冗余),同时块大小必须与嵌入模型、LLM 上下文预算一起考虑;上线后应针对业务语料做 recall@k 与回答质量评测再微调。

Q3 为什么对话直接调 OpenAI 兼容客户端,而不用 LangChain 的 ChatOpenAI?

因为本项目需要:全异步、SSE 流式逐字推送、细粒度异常降级、以及和 Java 端完全一致的 prompt 语义。原生 AsyncOpenAI 在这些场景下代码量更少、行为更透明;LangChain 的价值集中在分块和生态集成上。框架用不用,取决于它是否真的降低复杂度。

Q4 中英文混排文档切分有什么坑?

中文没有空格分词,默认按字符切会切断语义;必须把 。;, 等中文标点显式加入分隔符,且顺序要按语义粒度从大到小。另外 token 估算不能照搬英文"4 字符 ≈ 1 token",需要为中文单独校准(本 Java 端经验系数为 2.0 字符/token)。

Q5 RRF 融合为什么能混排向量分和 BM25 分?

向量相似度与 BM25 得分量纲不同,直接相加没有意义。RRF 只看每个文档在两个榜单中的名次,1/(k+rank) 把名次变成可比较的分值,规避了跨检索器分数不可比的问题。k=60 是常用平滑常数。

Q6 LLM 打分不稳定怎么办?

三个手段:temperature=0 关闭随机性;max_tokens=10 限制输出,配合 \b([1-9]|10)\b 正则提取;解析失败回退为中等分 5,而不是中断整条检索。

Q7 Redis 缓存 Embedding 的 Key 怎么设计?

rag:emb: + 文本 MD5。文本相同(内容完全一致)才能命中,天然对"重复文档/相同段落重新入库"友好;TTL 24 小时控制脏数据生命周期;Redis 故障时跳过缓存直接调 API。

Q8 Python 端和 Java 端怎么保证检索行为一致?

两边共用一套参数语义:candidate_k = max(top_k * 2, hybrid_top_k)、RRF 常数、Prompt 模板、字段映射(document_id/document_title/heading/publish_time)、重排截断 1000 字符。Python 端对每个 Java 类都有"对应 Java XXX"的注释锚点,方便双端对照评审。


九、技术亮点速览

  1. LangChain 精准落地:只引入真正带来增量的 RecursiveCharacterTextSplitter,中文分隔符栈 + 512/64 重叠,其余链路保持原生 async 控制力。
  2. 全异步 RAG:FastAPI + AsyncElasticsearch + AsyncOpenAI,检索、重排、生成全程协程化,SSE 逐字推送。
  3. 混合检索工程化:kNN + BM25 并行取 max(top_k×3, 30) 候选 → RRF(权重可调、保留双榜原始分)→ LLM 重排质检 → Top-5 入 Prompt。
  4. 成本与可用性双优:Embedding 走 rag:emb:{md5} Redis 缓存 24h;失败降级零向量/纯 BM25;Redis 可选依赖,坏缓存不坏主链路。
  5. 双后端对齐:字段、Prompt、检索参数与 Java 微服务版一一对应,代码注释保留 Java 锚点,跨语言可评审、可迁移。
  6. 引用可追溯:检索块带文档标题与章节,LLM 强制标注 [1][2],回答有据可查、前端有引用面板。
如果说 Java 版证明了"企业级 AI 系统的工程化能力",那么 Python 版 LangChain 的落地则证明了"用最少框架成本,把 RAG 每一环做扎实"的产品判断力——这正是 AI 工程里最稀缺的能力。
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏