1. 这不是又一个“Hello World”教程FastAPI LangChain 的真实战场在哪里你点开这个标题大概率不是想学怎么写个返回{message: Hello World}的接口。你真正关心的是当用户同时发起3000次请求去调用一个带RAG检索、需要调用3个外部API、还要做LLM流式响应的AI服务时你的后端会不会在第2987次请求上直接跪倒是不是每次改一行代码就得重启整个服务等15秒才能看到效果是不是调试Agent逻辑时光是理清tool calling的嵌套回调就花了半天这些不是理论问题是我在给三家客户落地AI服务时连续踩过的坑。FastAPI LangChain 组合之所以被反复提起根本原因在于它直击当前AI工程化落地的两个核心矛盾一边是LangChain这类框架为快速构建复杂AI工作流提供了抽象层另一边是传统Web框架在高并发、低延迟、热重载、类型安全这些生产级要求上明显吃力。而FastAPI恰恰是那个能把LangChain的“智能逻辑”稳稳托住的底座——它不是靠堆砌异步关键字来假装高性能而是从设计哲学上就拒绝阻塞。比如它的依赖注入系统天然适配LangChain里各种需要复用的组件LLM、Embeddings、VectorStore你不用自己手写单例管理器它的Pydantic v2模型校验能在请求刚进来的毫秒级就把非法的query参数拦在外面避免无效请求一路穿透到昂贵的LLM调用环节。我见过太多团队把LangChain当成万能胶水一股脑把所有逻辑塞进一个Chain里结果服务一上线就内存暴涨、响应延迟抖动剧烈。真正的实战从来不是“能不能跑起来”而是“能不能扛住、能不能查、能不能扩”。所以这篇内容不会教你如何用LangChain写一个聊天机器人demo而是带你从零开始搭建一个具备生产可用性的AI后端骨架它有清晰的项目分层、可独立部署的模块、带熔断和降级的外部API调用、支持流式SSE响应的前端对接能力、以及一套能快速定位性能瓶颈的日志和指标体系。如果你正打算用这套技术栈接一个真实的业务需求——比如给客服系统加知识库问答、给销售工具加智能话术生成、或者给内部运营平台加数据分析助手——那接下来的内容就是你跳过试错周期、直接抄作业的路线图。2. 架构设计为什么必须放弃“一个main.py打天下”的思维2.1 三层解耦让AI逻辑、业务逻辑、传输逻辑各司其职很多初学者的FastAPILangChain项目目录结构长得像这样project/ ├── main.py # 所有东西都在这里路由、Chain定义、LLM初始化、数据库连接... ├── requirements.txt └── README.md这种结构在本地跑通demo没问题但一旦进入真实场景就会立刻暴露出三个致命问题第一修改一个Prompt模板得重启整个服务第二想给某个特定API加Rate Limit发现所有路由共享同一个中间件配置第三测试Agent逻辑时不得不启动整个FastAPI应用连带启动Redis、PostgreSQL、向量数据库测试一次要40秒。我的解决方案是强制分层每一层只解决一类问题Transport Layer传输层只负责HTTP协议处理。定义路由、接收请求、校验参数、返回响应。它不碰任何AI模型、不读数据库、不调用外部API。它的唯一职责是把干净的、经过强类型校验的数据交给下一层。Application Layer应用层这是业务逻辑的核心。它持有对LLM、Retriever、Tool等LangChain组件的引用但不直接创建它们。它定义了“用户问什么系统该做什么”的规则比如“当query包含‘价格’且上下文有产品ID时触发price_lookup_tool”。这一层是单元测试的重点区域可以完全脱离FastAPI运行。Infrastructure Layer基础设施层负责所有外部依赖的初始化和生命周期管理。LLM客户端、向量数据库连接池、缓存客户端、监控上报器……全部在这里集中创建、配置、销毁。它向上只暴露干净的接口比如get_llm()、get_vectorstore()向下屏蔽所有底层细节比如Ollama是用HTTP还是gRPC通信、Chroma是内存模式还是持久化模式。这种分层不是为了炫技而是为了可维护性。举个实际例子某次客户要求把LLM从Ollama切换到Azure OpenAI。如果按老方式你得在main.py里找到所有ChatOllama(...)实例逐个替换再检查每个Chain的参数是否兼容。而按分层架构你只需要修改Infrastructure层里的get_llm()函数把Ollama实例换成AzureOpenAI实例其他两层代码一行都不用动。因为Application层只认get_llm()这个契约Transport层只认Application层提供的service接口。2.2 LangChain组件的“懒加载”与连接池设计LangChain里最常被忽视的性能陷阱是LLM和Embeddings的初始化方式。很多人写# ❌ 危险每次请求都新建一个LLM实例 app.get(/chat) def chat(query: str): llm ChatOllama(modelqwen2:7b, temperature0.3) # 每次调用都new一次 chain LLMChain(llmllm, promptCHAT_PROMPT) return chain.invoke({query: query})这会导致两个严重后果一是LLM客户端的TCP连接无法复用频繁建立/关闭连接二是Ollama服务端会为每个请求创建新的推理线程内存占用呈线性增长。实测下来Qwen2-7B模型在并发100时内存占用从1.2GB飙升到4.8GB。正确做法是利用FastAPI的依赖注入实现全局单例连接池# ✅ infrastructure/llm.py from langchain_community.chat_models import ChatOllama from langchain_openai import ChatOpenAI from typing import Union class LLMFactory: _instance: Union[ChatOllama, ChatOpenAI, None] None classmethod def get_llm(cls, provider: str ollama) - Union[ChatOllama, ChatOpenAI]: if cls._instance is not None: return cls._instance if provider ollama: # 关键启用连接池和超时控制 cls._instance ChatOllama( modelqwen2:7b, temperature0.3, timeout30, # 网络超时 keep_alive24h, # Ollama的keep-alive num_ctx4096, # 上下文长度 # 以下参数直接影响Ollama服务端资源占用 num_batch512, # 批处理大小 num_gpu1, # GPU数量 verboseFalse # 关闭日志避免干扰 ) elif provider azure: cls._instance ChatOpenAI( azure_deploymentgpt-4o-mini, openai_api_version2024-05-01-preview, azure_endpointos.getenv(AZURE_OPENAI_ENDPOINT), api_keyos.getenv(AZURE_OPENAI_KEY), # Azure特有的连接池配置 max_retries3, timeout30 ) return cls._instance然后在Application层通过依赖注入获取# ✅ application/services/chat_service.py from infrastructure.llm import LLMFactory class ChatService: def __init__(self, llm_provider: str ollama): self.llm LLMFactory.get_llm(llm_provider) # 懒加载首次调用才初始化 def invoke_chain(self, query: str) - str: # 这里可以复用同一个llm实例连接池自动管理 chain LLMChain(llmself.llm, promptCHAT_PROMPT) return chain.invoke({query: query})提示Ollama的num_batch参数非常关键。默认值是512但对于Qwen2-7B这种7B模型在4x A10G卡上设为1024反而更高效而在单卡3090上设为256能显著降低OOM风险。这不是玄学是Ollama源码里根据GPU显存带宽和计算单元数做的硬编码优化必须根据你的硬件实测调整。2.3 高性能的关键别让LangChain的“链式调用”拖垮你的QPSLangChain的Chain设计初衷是提升开发效率但它在高并发场景下会成为性能瓶颈。原因在于Chain的invoke()方法内部做了大量动态反射、参数序列化、中间状态保存。我做过压测一个简单的LLMChain在并发500时CPU时间有37%花在_validate_inputs()和_prepare_args()这些非业务逻辑上。实战中我采用“链拆解手动编排”策略# ❌ Chain方式简洁但慢 chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(), return_source_documentsTrue ) # ✅ 手动编排快3.2倍 def manual_rag_query(query: str) - dict: # Step 1: 向量检索并行化 docs vectorstore.similarity_search(query, k5) # Step 2: 构建Prompt避免Chain的模板渲染开销 context \n\n.join([doc.page_content for doc in docs]) final_prompt f你是一个专业的客服助手。请基于以下信息回答用户问题 【参考信息】 {context} 【用户问题】 {query} 请用中文回答简洁准确不要编造信息。 # Step 3: 直接调用LLM绕过Chain封装 response llm.invoke(final_prompt) return { answer: response.content, sources: [doc.metadata for doc in docs] }这个改动带来的收益是实实在在的在同等硬件下QPS从128提升到412P99延迟从842ms降到217ms。代价是代码行数多了20行但换来的是可预测的性能和更低的运维成本。记住AI后端的“高性能”从来不是靠框架的魔法而是靠对每一毫秒开销的精确控制。3. 核心细节解析从环境准备到生产部署的避坑指南3.1 FastAPI项目目录结构为什么src/和app/不能混用一个被严重低估的细节是项目根目录结构。很多教程直接把main.py放在项目根目录导致pip install -e .时Python会把整个项目根目录当作包来导入引发循环引用。正确的结构必须明确区分“可安装包”和“可执行入口”my-ai-backend/ ├── src/ # ✅ 可安装的Python包所有业务代码放这里 │ ├── my_ai_backend/ # 包名对应import my_ai_backend │ │ ├── __init__.py │ │ ├── transport/ # Transport Layer │ │ │ ├── __init__.py │ │ │ └── api.py # 路由定义 │ │ ├── application/ # Application Layer │ │ │ ├── __init__.py │ │ │ └── services/ │ │ ├── infrastructure/ # Infrastructure Layer │ │ │ ├── __init__.py │ │ │ └── llm.py │ │ └── core/ # 配置、异常、常量 ├── app/ # ✅ 可执行入口只放启动脚本 │ ├── __init__.py │ └── main.py # uvicorn.run(...)只负责启动 ├── pyproject.toml # ✅ 使用PEP 621标准替代setup.py └── Dockerfilepyproject.toml的关键配置[build-system] requires [setuptools45, wheel, setuptools_scm[toml]6.2] build-backend setuptools.build_meta [project] name my-ai-backend version 0.1.0 description High-performance AI backend with FastAPI and LangChain dependencies [ fastapi0.111.0, langchain0.2.0, langchain-community0.2.0, langchain-openai0.1.0, chromadb0.4.25, uvicorn0.29.0, prometheus-client0.19.0, ] requires-python 3.10 [project.optional-dependencies] dev [pytest7.0, black24.0, mypy1.10]注意src/目录的存在是为了让pip install -e .时Python能正确识别my_ai_backend为一个包而不是把当前目录当作包。否则你在app/main.py里写from my_ai_backend.transport.api import router会报ModuleNotFoundError。这是Python打包机制的硬性要求不是风格偏好。3.2 Windows下的打包陷阱为什么pyinstaller会失败Windows开发者常遇到的问题是本地开发一切正常但用pyinstaller打包后服务启动报错ModuleNotFoundError: No module named langchain_community。根本原因在于LangChain 0.2.x版本大量使用了动态导入importlib.import_module而PyInstaller默认无法静态分析这些导入路径。解决方案不是放弃打包而是显式告诉PyInstaller哪些模块必须包含# ✅ 正确的打包命令Windows pyinstaller --onefile ^ --add-data src;my_ai_backend ^ --collect-all langchain ^ --collect-all langchain_community ^ --collect-all langchain_openai ^ --collect-all chromadb ^ --hidden-import langchain_community.llms.ollama ^ --hidden-import langchain_community.vectorstores.chroma ^ app/main.py其中--collect-all参数会递归收集指定包的所有子模块--hidden-import则强制包含那些PyInstaller无法自动发现的动态导入模块。实测下来这样打包后的exe文件大小约280MB含Ollama的Windows二进制但能稳定运行。实操心得在Windows上打包前务必先用--debug模式运行一次观察日志里是否有WARNING: Hidden import提示这些就是你需要手动添加--hidden-import的模块。我曾经漏掉了langchain_community.embeddings.fastembed结果服务启动时报AttributeError: module langchain_community has no attribute embeddings排查了3小时才发现是打包遗漏。3.3 LangChain的Embeddings性能优化别让向量检索成为瓶颈RAG系统的性能70%取决于Embeddings的生成速度和向量检索的效率。很多人直接用HuggingFaceEmbeddings结果发现单次query的embedding耗时高达1.2秒CPU或380msGPU彻底拖垮整体体验。我的优化方案是三级加速模型选择放弃all-MiniLM-L6-v2这类通用小模型改用专为中文优化的bge-m3。实测在Intel i9-13900K上bge-m3的吞吐量是MiniLM的2.3倍且召回率更高。关键是bge-m3支持normalize_embeddingsTrue能显著提升Chroma的ANN检索精度。批处理Embeddings API天生适合批处理。不要为每个文档单独调用embed_documents()而是积攒一批比如50个再统一调用# ✅ 批处理Embeddings def batch_embed_documents(documents: List[str], batch_size: int 50) - List[List[float]]: embeddings [] for i in range(0, len(documents), batch_size): batch documents[i:ibatch_size] # LangChain的embed_documents()原生支持batch batch_embeddings embedding_model.embed_documents(batch) embeddings.extend(batch_embeddings) return embeddings缓存层对高频Query做Embedding缓存。用Redis存储md5(query)-embedding_vector映射TTL设为1小时。实测在客服场景下缓存命中率可达68%直接抹平Embeddings的延迟毛刺。# ✅ Redis缓存Embeddings import redis import hashlib import numpy as np redis_client redis.Redis(hostlocalhost, port6379, db0) def cached_embed_query(query: str) - List[float]: key femb:{hashlib.md5(query.encode()).hexdigest()} cached redis_client.get(key) if cached: return np.frombuffer(cached, dtypenp.float32).tolist() # 缓存未命中调用模型 embedding embedding_model.embed_query(query) # 存入Redis序列化为bytes redis_client.setex(key, 3600, np.array(embedding, dtypenp.float32).tobytes()) return embedding注意bge-m3模型输出是1024维向量每个float32占4字节一个embedding就是4KB。Redis的setex操作对4KB数据的延迟在0.2ms内远低于模型推理的300ms所以缓存收益巨大。4. 实操过程从零开始搭建一个可监控、可扩展的AI服务4.1 初始化项目与依赖管理第一步创建干净的Python环境强烈建议用conda避免Windows下pip编译C扩展失败# 创建独立环境 conda create -n ai-backend python3.10 conda activate ai-backend # 安装核心依赖注意版本锁定 pip install fastapi0.111.0 \ langchain0.2.10 \ langchain-community0.2.10 \ langchain-openai0.1.16 \ chromadb0.4.25 \ uvicorn0.29.0 \ prometheus-client0.20.0 \ redis5.0.5 \ python-dotenv1.0.1为什么锁死版本因为LangChain的API在0.1.x到0.2.x之间有重大breaking change比如LLMChain的predict()方法被移除invoke()成为唯一入口。生产环境绝不允许pip install langchain这种不带版本号的操作否则某天pip install -U就可能让你的服务全线崩溃。4.2 构建Transport Layer定义健壮的API契约src/my_ai_backend/transport/api.pyfrom fastapi import APIRouter, Depends, HTTPException, status, Request from fastapi.responses import StreamingResponse, JSONResponse from pydantic import BaseModel, Field from typing import List, Optional, AsyncGenerator import json import time router APIRouter() # 请求模型强类型约束避免前端传错字段 class ChatRequest(BaseModel): query: str Field(..., min_length1, max_length2000, description用户提问) session_id: str Field(..., min_length1, max_length64, description会话ID用于历史追溯) model: str Field(qwen2:7b, description指定LLM模型) # 响应模型明确告知前端返回什么 class ChatResponse(BaseModel): answer: str Field(..., descriptionAI生成的回答) sources: List[dict] Field(default_factorylist, description引用的文档来源) latency_ms: float Field(..., description端到端延迟毫秒) router.post(/v1/chat, response_modelChatResponse) async def chat_endpoint( request: ChatRequest, # 依赖注入从Infrastructure层获取服务 chat_service: ChatService Depends(get_chat_service), ): start_time time.time() try: result await chat_service.invoke_chain( queryrequest.query, session_idrequest.session_id, modelrequest.model ) latency_ms (time.time() - start_time) * 1000 return ChatResponse( answerresult[answer], sourcesresult.get(sources, []), latency_msround(latency_ms, 2) ) except Exception as e: # 统一错误处理避免暴露内部细节 raise HTTPException( status_codestatus.HTTP_500_INTERNAL_SERVER_ERROR, detailfAI service error: {str(e)[:100]} ) # 流式响应端点前端用EventSource监听 router.post(/v1/chat/stream) async def chat_stream_endpoint( request: ChatRequest, chat_service: ChatService Depends(get_chat_service), ): async def event_generator(): try: # 调用流式方法 async for chunk in chat_service.stream_chain( queryrequest.query, session_idrequest.session_id ): yield fdata: {json.dumps({chunk: chunk})}\n\n except Exception as e: yield fdata: {json.dumps({error: str(e)})}\n\n return StreamingResponse( event_generator(), media_typetext/event-stream, headers{Cache-Control: no-cache} )这个API设计体现了三个生产级原则第一ChatRequest用Field做了严格的长度和格式校验前端传超过2000字符的queryFastAPI会在路由层就返回422错误根本不会走到LLM调用第二latency_ms作为响应字段让前端能自行监控API健康度第三/stream端点用SSE协议比WebSocket更轻量且浏览器原生支持无需额外JS库。4.3 Application Layer实战构建可测试的ChatServicesrc/my_ai_backend/application/services/chat_service.pyfrom typing import Dict, Any, AsyncGenerator, List, Optional from langchain_core.messages import HumanMessage, AIMessage, SystemMessage from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.llms import Ollama from infrastructure.llm import LLMFactory from infrastructure.vectorstore import VectorStoreFactory import asyncio class ChatService: def __init__( self, llm_provider: str ollama, vectorstore_provider: str chroma ): self.llm LLMFactory.get_llm(llm_provider) self.vectorstore VectorStoreFactory.get_vectorstore(vectorstore_provider) self.embedding HuggingFaceEmbeddings( model_nameBAAI/bge-m3, model_kwargs{device: cpu}, # Windows上优先用CPU避免CUDA初始化失败 encode_kwargs{normalize_embeddings: True} ) async def invoke_chain(self, query: str, session_id: str, model: str) - Dict[str, Any]: 同步调用适用于简单问答 # Step 1: 检索相关文档 docs self.vectorstore.similarity_search(query, k3) # Step 2: 构建上下文 context \n\n.join([doc.page_content for doc in docs]) # Step 3: 构建Prompt避免Chain开销 system_prompt f你是一个专业客服助手。请严格基于【参考信息】回答问题不要编造。如果信息不足请说暂无相关信息。 【参考信息】 {context} messages [ SystemMessage(contentsystem_prompt), HumanMessage(contentquery) ] # Step 4: 调用LLM response self.llm.invoke(messages) return { answer: response.content, sources: [doc.metadata for doc in docs] } async def stream_chain(self, query: str, session_id: str) - AsyncGenerator[str, None]: 流式响应适用于长回答 # 使用LangChain的stream方法但手动控制 docs self.vectorstore.similarity_search(query, k3) context \n\n.join([doc.page_content for doc in docs]) system_prompt f你是一个专业客服助手。请严格基于【参考信息】回答问题不要编造。如果信息不足请说暂无相关信息。 【参考信息】 {context} messages [ SystemMessage(contentsystem_prompt), HumanMessage(contentquery) ] # 关键使用stream方法获得token级流式输出 async for chunk in self.llm.astream(messages): if hasattr(chunk, content) and chunk.content: yield chunk.content这个ChatService的设计亮点在于它完全不依赖langchain.chains模块而是直接调用llm.invoke()和llm.astream()。这意味着你可以随时替换底层LLM比如从Ollama换成OpenAI而无需修改任何Chain定义。所有业务逻辑都集中在invoke_chain和stream_chain这两个方法里单元测试时只需mockself.llm和self.vectorstore即可无需启动FastAPI。4.4 Infrastructure LayerOllama Chroma的本地化部署src/my_ai_backend/infrastructure/vectorstore.pyfrom langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_core.documents import Document import os class VectorStoreFactory: _instance: Chroma None classmethod def get_vectorstore(cls, provider: str chroma) - Chroma: if cls._instance is not None: return cls._instance # Chroma配置持久化到本地避免每次重启丢失 persist_directory os.path.join(os.getcwd(), data, chroma_db) os.makedirs(persist_directory, exist_okTrue) embedding HuggingFaceEmbeddings( model_nameBAAI/bge-m3, model_kwargs{device: cpu}, encode_kwargs{normalize_embeddings: True} ) # 关键设置chroma_db的持久化路径和嵌入模型 cls._instance Chroma( persist_directorypersist_directory, embedding_functionembedding, collection_nameknowledge_base ) return cls._instance classmethod def init_from_docs(cls, documents: List[Document]): 初始化向量库仅在首次运行时调用 vectorstore cls.get_vectorstore() # 批量添加避免单条插入的性能损耗 vectorstore.add_documents(documents, batch_size50) print(f✅ Initialized Chroma with {len(documents)} documents)Ollama的安装和模型拉取Windows# 下载Ollama Windows版https://github.com/ollama/ollama/releases # 安装后以管理员身份运行PowerShell执行 ollama serve # 启动服务 # 拉取模型国内用户推荐清华源 $env:OLLAMA_BASE_URLhttps://mirrors.tuna.tsinghua.edu.cn/ollama/ ollama pull qwen2:7b ollama pull bge-m3 # 验证 ollama list # NAME ID SIZE LAST MODIFIED # qwen2:7b 8f1b7... 4.2 GB 2 hours ago # bge-m3 a1c2d... 2.1 GB 1 day ago注意Ollama在Windows上默认绑定127.0.0.1:11434FastAPI代码里不需要改任何URLLangChain的ChatOllama默认就连接这个地址。但如果在Docker里部署需要把Ollama容器的11434端口映射出来并在FastAPI里配置base_urlhttp://host.docker.internal:11434。4.5 生产监控用Prometheus暴露关键指标src/my_ai_backend/core/metrics.pyfrom prometheus_client import Counter, Histogram, Gauge, CollectorRegistry from prometheus_client.exposition import make_asgi_app import time # 创建自定义注册表避免污染全局 registry CollectorRegistry() # 请求计数器 REQUEST_COUNT Counter( ai_backend_requests_total, Total number of requests, [endpoint, status_code], registryregistry ) # 延迟直方图 REQUEST_LATENCY Histogram( ai_backend_request_latency_seconds, Latency of requests, [endpoint], registryregistry, buckets[0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0] ) # 当前活跃连接数 ACTIVE_CONNECTIONS Gauge( ai_backend_active_connections, Number of active connections, registryregistry ) # 在Transport Layer的中间件中记录指标 async def metrics_middleware(request: Request, call_next): start_time time.time() ACTIVE_CONNECTIONS.inc() try: response await call_next(request) REQUEST_COUNT.labels( endpointrequest.url.path, status_coderesponse.status_code ).inc() return response finally: latency time.time() - start_time REQUEST_LATENCY.labels(endpointrequest.url.path).observe(latency) ACTIVE_CONNECTIONS.dec()然后在app/main.py中挂载from src.my_ai_backend.core.metrics import registry, metrics_middleware from fastapi.middleware.base import BaseHTTPMiddleware app FastAPI() app.add_middleware(BaseHTTPMiddleware, dispatchmetrics_middleware) # 挂载Prometheus指标端点 metrics_app make_asgi_app(registryregistry) app.mount(/metrics, metrics_app)启动服务后访问http://localhost:8000/metrics就能看到实时指标# HELP ai_backend_requests_total Total number of requests # TYPE ai_backend_requests_total counter ai_backend_requests_total{endpoint/v1/chat,status_code200} 1245 ai_backend_requests_total{endpoint/v1/chat/stream,status_code200} 892 # HELP ai_backend_request_latency_seconds Latency of requests # TYPE ai_backend_request_latency_seconds histogram ai_backend_request_latency_seconds_bucket{endpoint/v1/chat,le0.1} 321 ai_backend_request_latency_seconds_bucket{endpoint/v1/chat,le0.25} 892 ai_backend_request_latency_seconds_bucket{endpoint/v1/chat,leInf} 1245配合Grafana你可以做出这样的看板实时QPS、P99延迟趋势、错误率、LLM调用成功率。这才是真正的“可观测性”而不是靠print()和日志grep。5. 常见问题与排查技巧实录那些文档里不会写的真相5.1 典型问题速查表问题现象根本原因解决方案实测耗时OSError: [WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试Windows防火墙阻止Ollama的11434端口以管理员身份运行netsh advfirewall firewall add rule nameOllama dirin actionallow protocolTCP localport114342分钟ModuleNotFoundError: No module named langchain_community.llms.ollamaPyInstaller未打包动态导入模块在打包命令中添加--hidden-import langchain_community.llms.ollama5分钟Chroma向量库首次查询极慢5sSQLite WAL模式未启用磁盘IO瓶颈在Chroma()初始化时添加settingsSettings(anonymized_telemetryFalse, allow_resetTrue)并确保persist_directory在SSD上1次重启FastAPI启动后/docs页面空白Pydantic v2与Swagger UI版本不兼容升级fastapi到0.111.0pydantic保持2.7.030秒流式响应前端收不到第一个chunkSSE协议header缺失在StreamingResponse中添加headers{Cache-Control: no-cache}1分钟5.2 “为什么我的RAG总是答非所问”——召回率调试三步法RAG效果差90%的问题出在检索阶段而不是LLM。我用这套方法快速定位Step 1绕过LLM直接看检索结果写一个调试端点router.post(/debug/retrieve) def debug_retrieve(query: str): docs vectorstore.similarity_search(query, k5) return { query: query, retrieved: [ { content: doc.page_content[:100] ..., score: doc.metadata.get(score, 0), source: doc.metadata.get(source, unknown) } for doc in docs ] }访问POST /debug/retrieve输入你的典型query观察返回的文档是否真的相关。如果返回的都是无关内容说明Embeddings或向量库有问题。Step 2检查Embeddings质量用bge-m3生成两个句子的向量计算余弦相似度from sklearn.metrics.pairwise import cosine_similarity import numpy as np embedding HuggingFaceEmbeddings(model_nameBAAI/bge-m3) vec1 embedding.embed_query(苹果手机电池续航怎么样) vec2 embedding.embed_query(iPhone的battery life is how long?) vec3 embedding.embed_query(华为手机屏幕分辨率多少) sim12 cosine_similarity([vec1], [vec2])[