基于UnicomAI/wanwu框架构建中文AI应用：从RAG到智能体的实战指南

1. 项目概述：一个面向中文场景的AI应用开发框架

最近在折腾AI应用开发，特别是想做一些符合中文用户习惯的智能工具时，发现了一个挺有意思的开源项目——UnicomAI/wanwu。这个名字“万物”本身就挺有野心，暗示着它想成为连接AI与各类应用的“万物”桥梁。简单来说，wanwu是一个旨在降低AI应用开发门槛，尤其是针对中文场景优化的开源框架。它不是一个具体的AI模型，而更像是一个“工具箱”或“脚手架”，帮你把大语言模型（LLM）的能力，快速、便捷地集成到你的Web应用、自动化脚本或者智能客服等实际产品中。

如果你是一个开发者，厌倦了每次从零开始搭建LLM调用、管理对话历史、处理复杂提示词（Prompt）的繁琐流程；或者你是一个产品经理、创业者，想快速验证一个AI创意，但又不想在技术底层耗费太多时间，那么wanwu这类框架就值得你关注。它的核心价值在于，把那些通用的、重复的AI应用开发环节标准化、模块化，让你能更专注于业务逻辑和创新本身。接下来，我就结合自己的探索和试用，拆解一下wanwu的设计思路、核心用法以及在实际搭建中会遇到的那些“坑”。

1.1 核心需求与设计哲学

为什么我们需要wanwu这样的框架？这得从当前AI应用开发的痛点说起。直接调用OpenAI或国内大模型的API虽然直接，但当你想要构建一个稍具复杂度的应用时，一堆问题就冒出来了：对话状态如何管理？多轮对话的上下文怎么有效维护且不超Token限制？复杂的提示词模板如何优雅地编写和复用？不同模型API的差异如何适配？还有成本控制、流式输出、文件处理、工具调用（Function Calling）等等。

wanwu的设计哲学，正是为了解决这些工程化问题。它没有重新发明轮子，而是基于成熟的Python生态（比如LangChain、LlamaIndex的理念），做了一层更贴近中文开发者习惯的封装和优化。其核心需求可以归纳为三点：

1. 降低复杂度：通过提供高层级的抽象（如Agent、Chain），让开发者无需深入底层细节，就能组合出强大的AI工作流。
2. 提升开发效率：内置常用模块，如对话记忆管理、提示词模板库、多模型路由等，开箱即用，避免重复造轮子。
3. 专注中文优化：在提示词示例、工具集成、知识库处理等方面，默认考虑中文语境和国内常用工具（如搜索引擎、数据库），减少适配成本。

它的整体架构通常是分层的。最底层是模型层，封装了国内外主流大模型的API调用，提供统一的接口。中间是核心组件层，包括记忆（Memory）、提示词（Prompts）、工具（Tools）、索引（Indexes）等。最上层是应用层，提供了像智能体（Agent）、链（Chain）这样的高级抽象，让你通过“搭积木”的方式快速构建应用。这种设计使得wanwu既灵活，又能保证一定的开发效率。

2. 核心组件与模块深度解析

要玩转wanwu，必须理解它的几个核心组件。这些组件是构建一切AI应用的基石，它们的设计好坏直接决定了框架的易用性和能力上限。

2.1 模型提供者（LLMs）：统一的模型调用门面

wanwu支持接入多种大语言模型，无论是OpenAI的GPT系列、Anthropic的Claude，还是国内的通义千问、文心一言、智谱GLM等。它的巧妙之处在于提供了一个统一的调用接口。这意味着，你在业务逻辑中写的代码，比如llm.invoke(prompt)，在切换模型供应商时，可能只需要修改一行配置，而不需要重写整个调用逻辑。

这背后是适配器模式的应用。wanwu为每个支持的模型都编写了一个适配器类，这个类负责将框架内部统一的请求格式，转换为对应模型API所需的特定格式（包括HTTP请求头、参数映射、错误处理等），同时将模型返回的响应再标准化为框架内部的统一格式。例如，OpenAI的响应里可能叫choices[0].message.content，而另一个模型的响应可能叫output.text，适配器会把这些差异屏蔽掉，让你始终用response.content来获取结果。

注意：虽然接口统一了，但不同模型的能力、定价、上下文长度、速率限制差异巨大。在wanwu的配置中，你需要清晰地为每个模型配置api_key、base_url（如果使用代理或本地部署）以及model_name。对于国内模型，base_url的配置尤其关键，通常需要指向厂商提供的API网关地址。

2.2 提示词（Prompts）与模板引擎：告别字符串拼接噩梦

直接硬编码提示词字符串是初级做法，难以维护和复用。wanwu的提示词模块提供了强大的模板功能。你可以创建包含变量的模板，例如：

from wanwu import PromptTemplate template = """你是一个专业的{role}。请根据以下用户问题，用{style}的风格进行回答。 问题：{question} 回答：""" prompt = PromptTemplate.from_template(template)

然后，在运行时动态注入变量：

formatted_prompt = prompt.format(role="科技博主", style="轻松幽默", question="解释一下什么是机器学习？")

这带来了几个好处：一是提示词可以作为资产被管理起来，方便迭代优化；二是实现了逻辑与内容的分离；三是可以轻松支持多语言提示词切换。wanwu可能还会预置一些针对常见任务（如摘要、翻译、代码生成）优化过的中文提示词模板，这对中文开发者是实实在在的便利。

更高级的用法涉及少量示例（Few-shot）提示。wanwu可能会提供FewShotPromptTemplate组件，让你能方便地构建包含输入-输出示例的提示词，这对于引导模型完成特定格式的任务非常有效。

2.3 记忆（Memory）：让AI拥有“上下文”的能力

记忆是对话式AI的核心。wanwu的记忆模块负责在多次交互中持久化和管理上下文信息。它通常提供几种类型的记忆：

1. 对话缓冲记忆（ConversationBufferMemory）：最简单的一种，只是把所有的对话历史（Human和AI的发言）都保存在一个字符串或列表中。缺点是对话长了之后会消耗大量Token，且可能包含无关信息。
2. 对话缓冲窗口记忆（ConversationBufferWindowMemory）：只保留最近K轮对话，像一个滑动窗口。这能有效控制上下文长度，但会丢失早期的关键信息。
3. 对话摘要记忆（ConversationSummaryMemory）：每次交互后，用一个LLM对当前对话历史生成一个简要摘要，下次对话时只提供这个摘要和最新几轮对话。这在平衡上下文长度和信息保留上是一种折中方案，但会增加额外的API调用成本。
4. 向量存储记忆（VectorStoreRetrieverMemory）：这是更高级的模式。它将每轮对话的文本转换为向量，存入向量数据库（如Chroma、Milvus）。当需要回忆时，根据当前问题检索最相关的历史片段。这种方式能实现“长期记忆”和“关键信息提取”，但架构更复杂。

在wanwu中，记忆对象通常与链（Chain）或智能体（Agent）绑定。你需要根据应用场景选择。对于简单的客服机器人，缓冲窗口记忆可能就够了；对于需要深层次分析多轮对话的咨询系统，向量存储记忆会更合适。

2.4 工具（Tools）：扩展AI的“手和脚”

大模型本身是“大脑”，但它无法直接操作外部世界，比如查询数据库、调用API、执行计算。工具（Tools）就是给AI装的“手和脚”。wanwu的工具模块允许你将任何Python函数“包装”成一个工具，描述其功能，然后AI（特别是智能体）就能在需要时决定调用哪个工具。

定义一个工具通常需要：

1. 一个具体的执行函数。
2. 清晰的名称和描述（这很重要，AI靠描述来理解工具用途）。
3. 定义输入参数的模式（Schema）。

例如，定义一个查询天气的工具：

from wanwu import Tool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str = Field(description="需要查询天气的城市名称，例如：北京") def get_weather(city: str) -> str: # 这里模拟调用天气API return f"{city}的天气是晴，25摄氏度。" weather_tool = Tool( name="get_weather", description="根据城市名称查询实时天气信息。", args_schema=WeatherInput, func=get_weather )

智能体在分析用户问题“北京今天天气怎么样？”时，会“思考”是否需要调用工具，然后生成符合WeatherInput模式的参数（{"city": "北京"}），框架自动执行get_weather("北京")，并将结果返回给智能体，智能体再组织成最终回答给用户。这个过程实现了AI与真实世界的闭环。

2.5 索引与检索器（Indexes & Retrievers）：连接私有知识库

对于企业应用，让AI基于私有知识库（公司文档、产品手册、客服问答）进行回答是刚需。wanwu的索引模块就是用来解决这个问题的。其核心流程是“索引-检索-生成”（Retrieval-Augmented Generation, RAG）。

1. 索引（Indexing）：将你的文档（PDF、Word、TXT、网页）进行切分（Chunking），转换成向量（Embedding），然后存入向量数据库。wanwu可能会集成Chroma、FAISS、Milvus等轻量级向量数据库，方便本地部署。
2. 检索（Retrieval）：当用户提问时，将问题也转换成向量，在向量数据库中搜索相似度最高的文本片段（Chunks）。
3. 生成（Generation）：将检索到的相关片段作为上下文，和用户问题一起构成提示词，发送给LLM生成最终答案。

wanwu通过VectorStoreIndex和Retriever等类封装了这些步骤。你只需要准备好文档，调用几行代码就能构建起一个可查询的知识库。这里的关键在于文本切分策略和向量模型的选择。切分太小会丢失上下文，太大则检索不精准。对于中文，可能需要按句号、换行符进行切分，并尝试重叠窗口来保证语义连贯。向量模型方面，选择针对中文优化的模型（如text2vec、BGE系列）至关重要，英文模型对中文文本的向量表示效果通常不佳。

3. 实战构建：从零搭建一个智能技术问答助手

理论说了这么多，我们来动手搭建一个实际的应用：一个基于技术文档的智能问答助手。假设我们有一些wanwu框架本身的Markdown格式的文档，我们想让AI能回答关于如何使用wanwu的问题。

3.1 环境准备与依赖安装

首先，确保你的Python环境在3.8以上。创建一个新的虚拟环境是个好习惯。

# 创建并激活虚拟环境（以conda为例） conda create -n wanwu_demo python=3.10 conda activate wanwu_demo # 安装wanwu框架。由于是开源项目，通常从GitHub安装开发版或等待PyPI发布。 # 假设已发布到PyPI，则： pip install wanwu # 安装额外的依赖，如向量数据库、Embedding模型等。 # 这里我们使用Chroma（轻量级）和 sentence-transformers（用于生成向量） pip install chromadb sentence-transformers # 如果你需要使用OpenAI的模型，还需要安装openai库并配置API Key # pip install openai # 在环境变量中设置 OPENAI_API_KEY

实操心得：国内网络环境安装sentence-transformers和下载模型可能会比较慢。可以考虑使用国内镜像源，或者预先下载好模型文件（如paraphrase-multilingual-MiniLM-L12-v2，这是一个支持多语言的小模型）到本地，然后指定本地路径加载。

3.2 文档加载与知识库构建

我们将文档放在./docs目录下。使用wanwu提供的文档加载器。

import os from pathlib import Path from wanwu.document_loaders import DirectoryLoader, TextLoader from wanwu.text_splitter import RecursiveCharacterTextSplitter # 1. 加载文档 documents_path = Path("./docs") loader = DirectoryLoader(str(documents_path), glob="**/*.md", loader_cls=TextLoader) documents = loader.load() print(f"成功加载 {len(documents)} 个文档。") # 2. 分割文本 # 中文文档分割需要调整分隔符。这里按换行、句号、分号等分割，并设置块大小和重叠。 text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, # 每个文本块大约500字符 chunk_overlap=50, # 块之间重叠50字符，保持上下文 separators=["\n\n", "\n", "。", "；", "，", " ", ""] # 中文分隔符优先级 ) all_splits = text_splitter.split_documents(documents) print(f"文档被分割成 {len(all_splits)} 个文本块。")

接下来，我们需要为这些文本块生成向量。这里我们使用本地运行的sentence-transformers模型，避免调用外部API产生费用和延迟。

from wanwu.embeddings import HuggingFaceEmbeddings from wanwu.vectorstores import Chroma # 3. 生成嵌入向量并存入向量数据库 # 指定一个中文优化的嵌入模型 model_name = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" embeddings = HuggingFaceEmbeddings(model_name=model_name) # 创建向量存储。persist_directory指定持久化目录，这样下次可以直接加载，无需重新生成向量。 vectorstore = Chroma.from_documents( documents=all_splits, embedding=embeddings, persist_directory="./chroma_db" # 向量数据库存储路径 ) vectorstore.persist() # 持久化到磁盘 print("知识库向量化完成并已保存。")

3.3 构建检索问答链

知识库准备好了，现在构建一个链（Chain），它能把用户问题、检索到的文档、以及提示词模板组合起来，调用LLM生成答案。

from wanwu.llms import OpenAI # 示例使用OpenAI，也可换为其他 from wanwu.chains import RetrievalQA from wanwu import PromptTemplate import os # 0. 配置LLM (这里以OpenAI为例，需要设置API Key) os.environ["OPENAI_API_KEY"] = "your-api-key-here" # 如果使用国内模型，可能需要配置base_url，例如： # llm = OpenAI(model="qwen-turbo", api_key="your-key", base_url="https://dashscope.aliyuncs.com/compatible-mode/v1") llm = OpenAI(model="gpt-3.5-turbo", temperature=0.1) # temperature调低，让回答更确定 # 1. 从磁盘加载已有的向量数据库 embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2") vectorstore = Chroma(persist_directory="./chroma_db", embedding_function=embeddings) # 2. 将向量数据库转换为检索器 retriever = vectorstore.as_retriever(search_kwargs={"k": 4}) # 检索最相关的4个文本块 # 3. 定义自定义提示词模板，引导AI基于上下文回答 qa_prompt_template = """基于以下已知信息，简洁和专业地回答用户的问题。 如果无法从已知信息中得到答案，请说“根据已知信息无法回答该问题”，不要编造答案。 已知信息： {context} 问题： {question} 请用中文回答：""" QA_PROMPT = PromptTemplate.from_template(qa_prompt_template) # 4. 创建检索问答链 qa_chain = RetrievalQA.from_chain_type( llm=llm, chain_type="stuff", # “stuff”模式将检索到的所有文档内容都塞进提示词。还有“map_reduce”、“refine”等复杂模式。 retriever=retriever, chain_type_kwargs={"prompt": QA_PROMPT}, return_source_documents=True # 返回源文档，便于调试 )

3.4 测试与迭代优化

现在，我们可以测试这个问答助手了。

# 测试问题 query = "如何在wanwu中定义一个工具？" result = qa_chain.invoke({"query": query}) print(f"问题：{query}") print(f"答案：{result['result']}") print("\n--- 参考来源 ---") for i, doc in enumerate(result['source_documents'][:2]): # 打印前两个来源 print(f"[来源{i+1}] {doc.page_content[:200]}...") # 截取部分内容

运行后，你应该能得到一个基于文档的答案，并看到答案引用了哪些文本块。如果答案不准确，可以从以下几个方面排查和优化：

1. 检索质量：调整search_kwargs={"k": 4}中的k值，增加或减少检索数量。检查检索到的文档是否真的相关。如果不相关，可能是嵌入模型不适合你的领域，或者文本切分不合理（块太大或太小）。
2. 提示词工程：优化qa_prompt_template。指令可以写得更明确，比如“请严格依据已知信息”、“如果信息不足，请直接说明”等。你甚至可以要求AI在答案后标注引用来源的编号。
3. 链类型（chain_type）：对于长文档，stuff模式可能超出模型上下文限制。可以尝试map_reduce：先对每个文档块单独生成答案（map），再汇总这些答案生成最终答案（reduce）。虽然更复杂且调用次数多，但能处理更大量的文本。
4. 后处理：有时答案会包含无关信息或格式问题。你可以在链的输出后添加一个简单的后处理步骤，比如用正则表达式清理答案，或者用另一个小模型对答案进行润色和总结。

4. 高级应用：构建具有记忆和工具调用能力的智能体（Agent）

单纯的问答链还不够“智能”。一个真正的助手应该能记住对话历史，并能主动使用工具去完成复杂任务。这就需要用到wanwu的智能体（Agent）功能。智能体 = LLM（大脑）+ 记忆（经验）+ 工具（能力）+ 决策逻辑。

4.1 设计一个多功能技术助手智能体

假设我们要构建一个不仅能回答文档问题，还能查询最新技术动态（通过网页搜索工具）和进行简单计算的技术助手。

首先，定义工具。除了之前的知识库检索工具（可以包装成一个工具），我们还需要搜索和计算工具。

from wanwu.agents import Tool from wanwu.tools import DuckDuckGoSearchRun from langchain.tools import WikipediaQueryRun from langchain.utilities import WikipediaAPIWrapper import math # 工具1：网页搜索 (使用DuckDuckGo) search = DuckDuckGoSearchRun() # 工具2：维基百科查询 (需要安装 langchain-community) # pip install langchain-community wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper(top_k_results=2, lang="zh")) # 工具3：计算器 def calculator(expression: str) -> str: """计算一个数学表达式的值。支持 +, -, *, /, **, sqrt等。""" try: # 安全评估，避免执行任意代码。这里做简单处理，生产环境需更严格。 allowed_names = {"sqrt": math.sqrt, "pi": math.pi, "e": math.e} result = eval(expression, {"__builtins__": {}}, allowed_names) return str(result) except Exception as e: return f"计算错误：{e}" calc_tool = Tool( name="Calculator", func=calculator, description="用于计算数学表达式。输入应为一个字符串，如 '3 + 5 * 2' 或 'sqrt(16)'。" ) # 工具4：知识库问答 (将之前构建的qa_chain包装成工具) def query_knowledge_base(question: str) -> str: """回答关于wanwu框架使用的问题。""" result = qa_chain.invoke({"query": question}) return result['result'] kb_tool = Tool( name="Wanwu_Knowledge_Base", func=query_knowledge_base, description="专门回答关于wanwu开源框架的使用、配置和概念问题。" )

4.2 配置智能体与记忆系统

接下来，我们创建智能体，并为其配备对话记忆。

from wanwu.agents import initialize_agent, AgentType from wanwu.memory import ConversationBufferWindowMemory # 初始化记忆，保留最近5轮对话 memory = ConversationBufferWindowMemory(k=5, memory_key="chat_history", return_messages=True) # 准备工具列表 tools = [search, wikipedia, calc_tool, kb_tool] # 初始化智能体 # AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION 是一种适合对话场景的智能体类型，它使用ReAct（推理+行动）框架。 agent = initialize_agent( tools=tools, llm=llm, # 使用之前定义的llm agent=AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, memory=memory, verbose=True, # 开启详细日志，会打印智能体的“思考”过程，便于调试 handle_parsing_errors=True, # 优雅处理智能体输出解析错误 max_iterations=5 # 限制最大迭代次数，防止陷入循环 )

4.3 运行与调试：观察智能体的思考过程

让我们运行这个智能体，并观察它如何决策。

# 第一轮对话 response1 = agent.invoke({"input": "wanwu框架里，怎么管理对话记忆？"}) print("用户：wanwu框架里，怎么管理对话记忆？") print(f"助手：{response1['output']}\n") # 第二轮对话，测试记忆和工具切换 response2 = agent.invoke({"input": "我刚才问的是什么？顺便帮我搜一下大语言模型的最新进展。"}) print("用户：我刚才问的是什么？顺便帮我搜一下大语言模型的最新进展。") print(f"助手：{response2['output']}\n") # 第三轮对话，测试计算工具 response3 = agent.invoke({"input": "计算一下半径为3的圆的面积，用pi表示。"}) print("用户：计算一下半径为3的圆的面积，用pi表示。") print(f"助手：{response3['output']}")

当verbose=True时，你会在控制台看到类似以下的输出，这就是智能体的“思考链”（Chain of Thought）：

> Entering new AgentExecutor chain... 思考：用户问的是wanwu框架的具体功能，我应该使用Wanwu_Knowledge_Base工具。 行动：Wanwu_Knowledge_Base 行动输入：wanwu框架里，怎么管理对话记忆？ 观察：wanwu框架提供了ConversationBufferMemory, ConversationBufferWindowMemory等多种记忆类... 思考：我得到了答案，可以返回给用户了。 最终答案：wanwu框架通过Memory组件管理对话记忆，常见类型有...

这个过程清晰地展示了智能体是如何分析问题、选择工具、执行工具并整合结果的。通过观察这些日志，你可以判断工具描述是否清晰、智能体决策是否合理，从而进行优化。

5. 部署与性能优化考量

当你开发完成一个基于wanwu的应用后，下一步就是部署和优化。这里有几个关键点需要考虑。

5.1 应用封装与API服务化

本地脚本不适合对外服务。通常我们需要将应用封装成Web API。可以使用FastAPI这样的现代框架快速搭建。

# main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from your_agent_module import agent # 导入你之前构建的智能体 app = FastAPI(title="Wanwu 智能助手 API") class QueryRequest(BaseModel): message: str session_id: str = None # 用于区分不同会话的记忆 class QueryResponse(BaseModel): reply: str session_id: str @app.post("/chat", response_model=QueryResponse) async def chat(request: QueryRequest): try: # 这里需要一个更复杂的记忆管理，根据session_id加载对应的记忆对象。 # 简单示例：假设我们只有一个全局agent（实际生产环境需用数据库或Redis存储记忆） response = agent.invoke({"input": request.message}) return QueryResponse(reply=response['output'], session_id=request.session_id or "default") except Exception as e: raise HTTPException(status_code=500, detail=str(e)) if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8000)

然后使用uvicorn main:app --reload启动服务。生产环境则需要使用Gunicorn或Uvicorn配合多进程，并设置反向代理（如Nginx）。

5.2 性能瓶颈分析与优化策略

AI应用的性能瓶颈通常出现在以下几个方面：

1. LLM API调用延迟：这是最主要的延迟来源。优化策略包括：

   • 缓存：对相同或相似的查询结果进行缓存。可以使用langchain.cache（如果wanwu集成）或外部缓存如Redis。
   • 批处理：如果有多条独立消息需要处理，可以考虑批量调用API（如果模型支持）。
   • 模型选型：在效果可接受的情况下，选择响应更快的模型（如gpt-3.5-turbo比gpt-4快）。
   • 设置超时和重试：配置合理的请求超时和失败重试机制，增加鲁棒性。

2. 嵌入向量生成速度：如果使用本地Embedding模型，其推理速度可能成为瓶颈，尤其是在处理大量文档或实时性要求高的检索场景。

   • 模型轻量化：使用更小的模型，如all-MiniLM-L6-v2，在速度和效果间权衡。
   • 硬件加速：确保使用了GPU（CUDA）进行推理。检查sentence-transformers是否自动检测到了CUDA。
   • 异步处理：对于非实时索引任务，使用异步队列（如Celery）后台处理。

3. 向量检索速度：当向量库规模很大时（百万级以上），检索可能变慢。

   • 索引优化：使用高效的向量索引算法，如HNSW（Chroma和FAISS默认支持）。
   • 过滤：在检索时添加元数据过滤（如文档类型、日期范围），缩小搜索空间。
   • 分片：将向量数据库分片，分布式部署。

4. 智能体推理循环：智能体可能会为了一个问题多次调用工具和LLM（迭代），导致响应时间叠加。

   • 限制迭代次数：如我们之前设置的max_iterations=5，防止死循环。
   • 优化工具描述：清晰、精确的工具描述能帮助智能体更快做出正确决策，减少无效尝试。
   • 设计更高效的链：有时，一个精心设计的单一链（Chain）比一个通用智能体更高效、更可控。

5.3 成本控制与监控

对于使用付费API（如OpenAI）的应用，成本控制至关重要。

• Token计数与估算：在调用LLM前后，计算提示词和返回结果的Token数量。wanwu的LLM包装器通常能提供get_num_tokens方法或类似功能。监控每个请求的Token消耗。
• 设置预算与告警：在应用层面或使用云服务商的监控告警，设置每日/每周的API调用费用预算，超限则告警或自动降级（如切换到更便宜的模型）。
• 使用更经济的组件：
  • 在RAG中，使用本地Embedding模型而非API。
  • 对于简单任务，使用小模型（如gpt-3.5-turbo）。
  • 对智能体进行“瘦身”，减少不必要的工具调用和迭代。
• 日志与审计：详细记录每一次LLM调用、工具调用的输入输出和消耗，便于后续分析和优化。

6. 常见问题与排查技巧实录

在实际开发和部署wanwu应用的过程中，我踩过不少坑。这里把一些典型问题和解决方法记录下来，希望能帮你节省时间。

6.1 模型响应慢或超时

• 现象：调用LLM API时长时间无响应，最终超时。
• 排查：
  1. 网络问题：首先用curl或ping测试到API端点的网络连通性和延迟。国内调用国外API慢是常态。
  2. 模型负载：某些热门模型在高峰时段可能响应慢。可以尝试重试，或设置更长的超时时间。
  3. 提示词过长：过长的上下文会导致模型计算时间显著增加。检查你的提示词是否包含了不必要的冗长内容。对于RAG，考虑优化检索数量（k值）或使用map_reduce等处理长上下文的方法。
  4. 流式输出：如果不需要逐字输出，可以关闭流式传输（stream=False），有时能更快获得完整响应。
• 解决：
  • 对于网络问题，考虑使用可靠的代理服务（注：此处需严格遵守安全要求，仅作技术问题描述，不提供任何具体方案或暗示）。
  • 在代码中实现指数退避重试机制。
  • 优化提示词，精简上下文。
  • 考虑使用区域更近或专有的API端点（如果模型提供商支持）。

6.2 智能体陷入循环或调用错误工具

• 现象：智能体反复执行同一个操作，或者总是选择不合适的工具。
• 排查：
  1. 观察思考链（verbose=True）：这是最重要的调试手段。看智能体每一步的“思考”和“行动”，分析其决策逻辑哪里出了问题。
  2. 工具描述：检查工具的描述（description）是否清晰、无歧义？是否准确反映了工具的功能和适用场景？模糊的描述会导致智能体误解。
  3. 提示词模板：智能体内部也有一个系统提示词，指导其如何使用工具。wanwu可能允许你自定义这个提示词。检查它是否给出了清晰的指令，比如“在回答关于wanwu框架的问题时，优先使用知识库工具”。
• 解决：
  • 优化工具描述：重写工具描述，使其更精确。例如，将“搜索工具”改为“用于搜索互联网上最新、实时的公开信息，如新闻、事件。不适用于查询静态知识或文档。”
  • 调整工具顺序：有些智能体实现会按工具列表顺序有一定偏好，把更可能用到的工具放前面。
  • 自定义智能体提示词：如果框架支持，提供一个更强大的系统提示词，明确约束和引导智能体的行为。
  • 设置迭代上限：务必设置max_iterations，这是防止死循环的最后防线。

6.3 检索到的内容不相关，导致答案质量差

• 现象：RAG问答的答案胡言乱语，或者“根据已知信息无法回答”的频率很高，但检查发现检索到的文档片段确实不相关。
• 排查：
  1. 嵌入模型：你使用的嵌入模型是否适合你的文档领域？用通用模型处理高度专业的技术文档可能效果不佳。
  2. 文本切分（Chunking）：这是最常见的问题。块大小（chunk_size）设置是否合理？500-1000字符对于中文技术文档可能是个起点。块重叠（chunk_overlap）是否足够（通常50-150字符）以保证边界句子语义完整？
  3. 检索策略：检索器是简单的相似度搜索吗？可以尝试MMR（最大边际相关性）搜索，它在保证相关性的同时增加结果的多样性。调整检索数量k。
  4. 元数据过滤：如果你的文档有标题、章节等元数据，可以在检索时加入过滤条件，提高精度。
• 解决：
  • 尝试不同的嵌入模型：在中文领域，可以尝试BAAI/bge-large-zh、moka-ai/m3e-base等效果公认较好的模型。
  • 优化切分策略：不要只用字符分割。尝试按段落、按标题分割。RecursiveCharacterTextSplitter可以配置多级分隔符，对于Markdown，可以尝试用"#", "##", "###", "\n\n", "\n"作为分隔符。
  • 重排序（Re-ranking）：在初步检索出较多结果（如10个）后，使用一个更精细的交叉编码器（Cross-Encoder）模型对结果进行重排序，只取Top-k个最相关的。这能显著提升精度，但会增加计算开销。
  • 混合搜索：结合基于向量的语义搜索和基于关键词的稀疏搜索（如BM25），取长补短。

6.4 记忆管理在并发环境下的问题

• 现象：在Web服务中，多个用户共享同一个全局记忆对象，导致对话串线。
• 排查：检查你的记忆对象是否是全局单例。在类似FastAPI的应用中，如果在模块级别初始化一个ConversationBufferMemory，那么所有请求都会读写同一块内存。
• 解决：
  • 会话隔离：必须为每个用户会话（通常用session_id标识）创建独立的记忆实例。
  • 记忆存储后端：不要使用内存存储，而是使用可以持久化且支持键值查询的后端，如Redis、数据库。你需要实现一个自定义的Memory类，或者利用wanwu/LangChain可能提供的RedisChatMessageHistory等组件。
  • 请求生命周期管理：在Web请求的入口处，根据session_id从存储中加载历史消息，构造记忆对象，传递给智能体；在请求结束后，将更新的记忆保存回存储。

# 伪代码示例 from wanwu.schema import AIMessage, HumanMessage import redis import json class RedisMemoryManager: def __init__(self, redis_client, ttl=3600): self.redis = redis_client self.ttl = ttl # 记忆保存时间 def get_memory_for_session(self, session_id: str): key = f"chat_memory:{session_id}" history_json = self.redis.get(key) if history_json: messages = [AIMessage(**m) if m['type']=='ai' else HumanMessage(**m) for m in json.loads(history_json)] # 用历史消息构建一个记忆对象 from wanwu.memory import ConversationBufferWindowMemory memory = ConversationBufferWindowMemory(k=5, return_messages=True) memory.chat_memory.messages = messages return memory else: return ConversationBufferWindowMemory(k=5, return_messages=True) def save_memory_for_session(self, session_id: str, memory): key = f"chat_memory:{session_id}" messages = memory.chat_memory.messages messages_dict = [{"type": "ai" if isinstance(m, AIMessage) else "human", "content": m.content} for m in messages] self.redis.setex(key, self.ttl, json.dumps(messages_dict)) # 在FastAPI路由中使用 @app.post("/chat") async def chat(request: QueryRequest): memory_manager = RedisMemoryManager(redis_client) memory = memory_manager.get_memory_for_session(request.session_id) # 用这个memory去初始化agent agent = initialize_agent(..., memory=memory) response = agent.invoke(...) # 保存更新后的记忆 memory_manager.save_memory_for_session(request.session_id, memory) return response

这个例子展示了如何将会话记忆持久化到Redis，实现了多用户环境的隔离。生产环境中还需要考虑内存清理、会话过期等更多细节。