大模型应用开发全栈实战：从API调用到RAG与Agent项目构建

最近在尝试将大模型集成到自己的业务系统中时你是否也遇到了这样的困境网上资料要么是零散的API调用示例要么是过于学术化的论文解读真正能串联起从环境搭建、API调用、Prompt工程到RAG、Agent项目实战的完整教程少之又少。自己摸索光是环境配置和依赖冲突就足以劝退更别提理解复杂的架构设计和性能优化了。本文正是为了解决这个问题而生。它不是简单的概念罗列而是一套为大模型应用开发者量身定制的“从入门到上线”全栈实战指南。无论你是希望转型AI的后端/前端工程师还是在校学生想快速上手项目甚至是产品经理想理解技术边界都能从这套教程中找到清晰的路径。我们将从最核心的LLM API调用开始逐步深入到RAG检索增强和Agent智能体开发最终带你完成一个可运行、可扩展的实战项目。学完本系列你将能独立完成一个具备知识库问答和任务规划能力的智能应用原型。1. 大模型应用开发核心概念与生态全景在动手写代码之前我们必须先理清几个关键概念这能帮助你在纷繁的技术选型中做出正确判断。1.1 什么是大模型应用开发大模型应用开发本质上不是去训练一个全新的GPT或LLaMA而是基于现有的、强大的基础大模型Foundation Model通过工程化的手段构建能够解决特定业务问题的软件应用。你可以把它类比为“基于云服务如AWS、阿里云开发应用”只不过这里的“云服务”变成了提供智能能力的“大模型”。其核心工作流通常包括模型接入调用大模型提供的API如OpenAI的ChatCompletion或开源模型的本地API。提示工程设计高质量的提示词Prompt引导模型生成符合预期的输出。上下文管理处理超长文本的输入输出利用模型的上下文窗口。应用架构将大模型能力嵌入到传统软件架构中如Web后端、移动端、桌面应用等。性能与成本优化通过缓存、流式输出、模型选择等手段平衡效果、速度和费用。1.2 关键组件与技术栈一个完整的大模型应用通常涉及以下技术栈了解它们是你构建项目的基础大模型服务闭源/云服务OpenAI GPT系列、Google Gemini、Anthropic Claude、国内各大厂的云服务。优势是效果稳定、使用简单但需付费且数据需出境合规性需注意。开源模型本地部署LLaMA系列、ChatGLM、Qwen、Baichuan等。通过Ollama、vLLM、Transformers等框架部署在自有服务器。优势是数据可控、可定制化微调但对硬件有要求。开发框架与工具LangChain/LlamaIndex当前最主流的应用开发框架。它们将大模型调用、数据检索、记忆、工具使用等能力抽象成模块让你像搭积木一样构建复杂应用如RAG、Agent。LangChain更通用LlamaIndex更专注于数据索引和检索。Semantic Kernel微软推出的框架理念与LangChain类似与.NET生态结合更紧密。向量数据库实现RAG检索增强生成的核心。用于存储文本的向量化表示实现相似性搜索。常见的有Pinecone云服务、Chroma轻量级本地、Weaviate、Qdrant、Milvus等。传统开发栈你的应用外壳。可以是Python FastAPI/Django构建的Web后端也可以是JavaScript/React构建的前端或者是Java/Spring Boot服务。1.3 典型应用场景理解场景能帮你明确学习目标智能问答机器人基于企业文档、知识库的客服、技术支持系统。内容生成与辅助自动生成报告、邮件、营销文案、代码注释。数据分析与洞察让模型理解表格、日志数据并回答相关问题。智能体能自主使用工具如搜索、计算、操作软件完成复杂任务的AI Agent例如自动订票、数据分析Agent。2. 环境准备打造专属开发工作站工欲善其事必先利其器。一个稳定、可复现的开发环境是高效学习的前提。本节将详细配置一个基于Python的大模型应用开发环境。2.1 基础软件安装请确保你的操作系统是Windows 10/11, macOS或Linux (如Ubuntu 20.04)。我们将使用Python作为主要开发语言。Python安装推荐使用Python 3.10或3.11这是大多数AI框架兼容性最好的版本。访问 python.org 下载安装包。关键步骤安装时务必勾选 “Add Python to PATH”这样可以在命令行中直接使用python命令。验证安装打开终端Windows CMD/PowerShell, macOS Terminal, Linux Shell输入python --version # 或 python3 --version应显示类似Python 3.10.12的信息。包管理工具pip升级确保pip是最新版本。python -m pip install --upgrade pip代码编辑器/IDE强烈推荐使用Visual Studio Code (VSCode)。下载地址 code.visualstudio.com安装后建议安装以下扩展Python(Microsoft官方扩展)Pylance(更好的Python语言支持)Jupyter(用于运行代码片段和实验)版本控制Git用于管理代码和项目。下载地址 git-scm.com安装后在终端配置你的用户名和邮箱git config --global user.name Your Name git config --global user.email your.emailexample.com2.2 创建虚拟环境与管理依赖为每个项目创建独立的虚拟环境可以避免包版本冲突这是Python开发的最佳实践。创建项目目录并进入mkdir llm-app-tutorial cd llm-app-tutorial创建虚拟环境Windows:python -m venv venv venv\Scripts\activate # 激活环境macOS/Linux:python3 -m venv venv source venv/bin/activate # 激活环境激活后命令行提示符前通常会显示(venv)表示你已进入该虚拟环境。创建依赖管理文件在项目根目录创建requirements.txt文件初期内容如下# 核心大模型应用开发库 langchain0.1.0 langchain-community0.0.10 langchain-openai0.0.5 # OpenAI官方SDK (如果你使用OpenAI API) openai1.12.0 # 轻量级向量数据库用于本地RAG实验 chromadb0.4.22 # 文本分割和加载 tiktoken0.5.2 # OpenAI的Tokenizer用于计算Token pypdf3.17.4 # 用于读取PDF python-dotenv1.0.0 # 用于管理环境变量 # Web框架用于构建API fastapi0.104.1 uvicorn0.24.0注意框架版本迭代很快以上版本为撰写时的稳定版本。在实际项目中请根据官方文档和兼容性要求进行调整。安装依赖pip install -r requirements.txt如果安装缓慢可以考虑使用国内镜像源例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple2.3 获取大模型API密钥要调用云端大模型你需要一个API密钥。这里以OpenAI为例你也可以选择国内合规的同类服务如智谱AI、百度文心、阿里通义等其调用方式类似。访问 OpenAI Platform 并注册/登录。点击右上角个人头像选择 “View API keys”。点击 “Create new secret key”生成一个密钥并立即妥善保存关闭页面后将无法再次查看完整密钥。安全警告API密钥如同密码切勿直接硬编码在代码中或提交到GitHub等公开仓库。使用环境变量管理密钥在项目根目录创建.env文件注意文件名以点开头并写入OPENAI_API_KEY你的实际API密钥然后在代码中通过python-dotenv加载from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的变量 api_key os.getenv(OPENAI_API_KEY)务必在.gitignore文件中添加.env防止密钥泄露。3. 第一行代码与大模型对话现在让我们写下与大模型交互的第一行代码感受其能力。我们将从最基础的直接API调用开始然后过渡到使用LangChain框架。3.1 方式一使用OpenAI官方SDK直接调用这是最原始、最直接的方式帮助你理解底层交互。在项目根目录创建文件basic_openai.py。编写代码如下import os from openai import OpenAI from dotenv import load_dotenv # 1. 加载环境变量 load_dotenv() # 2. 初始化客户端 client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) # 3. 定义对话消息 messages [ {role: system, content: 你是一个乐于助人的编程助手。}, {role: user, content: 用Python写一个函数计算斐波那契数列的第n项。} ] # 4. 发起API调用 try: response client.chat.completions.create( modelgpt-3.5-turbo, # 指定模型也可用 gpt-4, gpt-4-turbo-preview 等 messagesmessages, temperature0.7, # 控制随机性0-2之间越高越随机 max_tokens500, # 限制生成的最大token数 ) # 5. 提取并打印回复 answer response.choices[0].message.content print(AI回复) print(answer) # 打印使用情况可选 print(f\n本次消耗Token数{response.usage.total_tokens}) except Exception as e: print(f调用API时出错{e})运行脚本python basic_openai.py如果一切正常你将看到AI生成的Python函数代码以及本次请求消耗的Token数。关键参数解释model: 选择要使用的模型。不同模型在能力、价格、速度上差异很大。temperature: 创造性参数。0表示输出非常确定、保守1或更高表示更具创造性、随机性。对于代码生成通常用较低值如0.2-0.8。max_tokens: 限制生成内容的长度。需注意输入和输出的总Token数不能超过模型的上下文窗口如GPT-3.5-turbo是16385个Token。3.2 方式二使用LangChain框架调用LangChain将调用过程模块化为构建复杂应用打下基础。创建文件basic_langchain.py。编写代码如下import os from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage, SystemMessage from dotenv import load_dotenv load_dotenv() # 1. 初始化LLM模型对象 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0.7, api_keyos.getenv(OPENAI_API_KEY) ) # 2. 构建消息链LangChain Chat Models 期望的消息格式 messages [ SystemMessage(content你是一个精通中国历史的专家。), HumanMessage(content请简要介绍秦始皇的主要功绩。) ] # 3. 调用并流式输出结果更优的交互体验 print(AI回复流式) for chunk in llm.stream(messages): if chunk.content is not None: print(chunk.content, end, flushTrue) # 逐块打印模拟打字效果 print() # 最后换行运行脚本python basic_langchain.py你将看到模型以“流式”的方式逐字输出回答体验更佳。LangChain的优势初显标准化接口无论后端是OpenAI、Anthropic还是本地部署的模型调用方式基本一致。流式支持内置.stream()方法方便实现打字机效果。为链式调用做准备ChatOpenAI对象可以轻松地与其他LangChain组件如提示模板、输出解析器连接。4. 核心技能Prompt工程与链式调用仅仅一次问答无法满足复杂需求。Prompt工程和链式调用是构建可靠应用的关键。4.1 构建可复用的提示模板硬编码提示词难以维护。LangChain的PromptTemplate可以解决这个问题。创建文件prompt_template.pyfrom langchain.prompts import ChatPromptTemplate, HumanMessagePromptTemplate, SystemMessagePromptTemplate from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, api_keyos.getenv(OPENAI_API_KEY)) # 1. 定义模板字符串使用花括号 {} 表示变量 system_template 你是一位专业的{role}。请用{style}的风格回答用户问题。 human_template 我的问题是{question} # 2. 创建消息提示模板 system_message_prompt SystemMessagePromptTemplate.from_template(system_template) human_message_prompt HumanMessagePromptTemplate.from_template(human_template) # 3. 组合成聊天提示模板 chat_prompt ChatPromptTemplate.from_messages([system_message_prompt, human_message_prompt]) # 4. 格式化模板传入变量值 formatted_messages chat_prompt.format_prompt( role美食评论家, style幽默风趣, question评价一下西红柿炒鸡蛋这道菜。 ).to_messages() # 5. 调用模型 response llm.invoke(formatted_messages) print(response.content)运行此脚本你会得到一个由“幽默风趣的美食评论家”生成的关于西红柿炒鸡蛋的评价。通过修改变量role、style和question你可以轻松复用这个模板处理不同场景。4.2 实现链式调用链Chain是LangChain的核心抽象它将LLM与其他组件提示模板、工具、其他链等串联起来形成一个可执行的工作流。创建文件simple_chain.py实现一个“翻译总结”的链from langchain.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI from langchain.schema.output_parser import StrOutputParser from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, api_keyos.getenv(OPENAI_API_KEY)) # 定义第一个链翻译链 translate_template ChatPromptTemplate.from_template( 请将以下英文文本翻译成地道的中文{text} ) translate_chain translate_template | llm | StrOutputParser() # 符号 | 是LangChain LCEL语法表示“然后”非常直观。 # 定义第二个链总结链 summarize_template ChatPromptTemplate.from_template( 请用一句话总结以下中文文本的核心内容{chinese_text} ) summarize_chain summarize_template | llm | StrOutputParser() # 组合链先翻译再总结 combined_chain translate_chain | summarize_chain # 注意translate_chain的输出会自动作为summarize_chain的输入变量名需对应。 # 运行组合链 english_text Artificial intelligence (AI) is intelligence demonstrated by machines, as opposed to the natural intelligence displayed by animals including humans. Leading AI textbooks define the field as the study of intelligent agents: any system that perceives its environment and takes actions that maximize its chance of achieving its goals. result combined_chain.invoke({text: english_text}) print(原文英文) print(english_text) print(\n链式处理结果翻译总结) print(result)这个例子展示了如何将简单的操作组合成复杂的工作流。在真实项目中链可以包含数据库查询、API调用、条件判断等。5. 项目实战构建本地知识库问答系统现在我们综合运用所学知识构建一个最经典的大模型应用——RAG检索增强生成系统。它能让大模型基于你提供的私有文档如公司手册、产品文档进行回答避免“幻觉”并增强专业性。5.1 项目架构与流程我们的系统将遵循标准的RAG流程文档加载读取本地PDF/TXT文件。文本分割将长文档切分成适合模型处理的小块。向量化与存储将文本块转换为向量Embedding并存入向量数据库。检索当用户提问时将问题也转换为向量并在数据库中查找最相关的文本块。增强生成将检索到的相关文本块作为上下文与用户问题一起构成提示词发送给大模型生成最终答案。5.2 代码实现创建项目目录rag_demo并在其中创建以下文件。第一步准备文档与依赖在rag_demo目录下创建一个data文件夹放入你的知识文档例如product_manual.pdf或knowledge.txt。同时创建requirements.txt内容同第2.2节。第二步实现核心RAG流水线创建rag_pipeline.pyimport os from dotenv import load_dotenv from langchain_community.document_loaders import PyPDFLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.prompts import ChatPromptTemplate from langchain.schema.runnable import RunnablePassthrough from langchain.schema.output_parser import StrOutputParser # 加载环境变量 load_dotenv() OPENAI_API_KEY os.getenv(OPENAI_API_KEY) class RAGSystem: def __init__(self, data_path, persist_directory./chroma_db): 初始化RAG系统 :param data_path: 知识文档路径.pdf 或 .txt :param persist_directory: 向量数据库持久化目录 self.data_path data_path self.persist_directory persist_directory self.embeddings OpenAIEmbeddings(api_keyOPENAI_API_KEY) self.llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.1, api_keyOPENAI_API_KEY) # 低temperature保证答案稳定 self.vectorstore None self.retriever None self.chain None def load_and_split_documents(self): 加载并分割文档 print(f正在加载文档{self.data_path}) if self.data_path.endswith(.pdf): loader PyPDFLoader(self.data_path) else: # 假设是txt文件 loader TextLoader(self.data_path, encodingutf-8) documents loader.load() # 文本分割器按字符递归分割保持语义段落 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块的最大字符数 chunk_overlap50, # 块之间的重叠字符避免上下文断裂 separators[\n\n, \n, 。, , , , , , ] ) splits text_splitter.split_documents(documents) print(f文档分割为 {len(splits)} 个文本块。) return splits def create_vectorstore(self, splits): 创建并持久化向量存储 print(正在创建向量数据库...) # 将分割后的文本转换为向量并存入ChromaDB self.vectorstore Chroma.from_documents( documentssplits, embeddingself.embeddings, persist_directoryself.persist_directory ) self.vectorstore.persist() # 持久化到磁盘 print(f向量数据库已保存至{self.persist_directory}) def load_vectorstore(self): 从磁盘加载已有的向量存储 if os.path.exists(self.persist_directory): print(加载已有向量数据库...) self.vectorstore Chroma( persist_directoryself.persist_directory, embedding_functionself.embeddings ) return True else: print(未找到已有的向量数据库需要重新创建。) return False def setup_retriever(self, k3): 设置检索器返回最相关的k个文本块 if self.vectorstore is None: raise ValueError(向量数据库未初始化请先调用 create_vectorstore 或 load_vectorstore。) self.retriever self.vectorstore.as_retriever(search_kwargs{k: k}) print(f检索器已就绪将返回最相关的 {k} 个片段。) def setup_chain(self): 构建RAG链 # 定义提示模板 template 请根据以下上下文信息回答问题。如果上下文信息不足以回答问题请直接说“根据提供的资料我无法回答这个问题”不要编造信息。 上下文信息 {context} 问题{question} 请给出专业、准确的回答 prompt ChatPromptTemplate.from_template(template) # 构建链检索 - 格式化上下文 - 生成回答 self.chain ( {context: self.retriever, question: RunnablePassthrough()} | prompt | self.llm | StrOutputParser() ) print(RAG问答链构建完成。) def initialize(self, force_recreateFalse): 初始化系统加载或创建向量库并构建链 if not force_recreate and self.load_vectorstore(): # 成功加载已有数据库 pass else: # 需要重新创建 splits self.load_and_split_documents() self.create_vectorstore(splits) self.setup_retriever() self.setup_chain() print(RAG系统初始化完成) def ask(self, question): 向系统提问 if self.chain is None: raise ValueError(问答链未初始化请先调用 initialize() 方法。) print(f\n你的问题{question}) print(正在检索并生成答案...) answer self.chain.invoke(question) print(f\n系统回答{answer}) return answer if __name__ __main__: # 使用示例 data_file ./data/your_knowledge.pdf # 替换为你的文件路径 rag RAGSystem(data_pathdata_file) # 初始化首次运行会创建向量库后续运行会直接加载 rag.initialize(force_recreateFalse) # 设置为True可强制重建向量库 # 进行问答 while True: user_question input(\n请输入你的问题输入quit退出) if user_question.lower() quit: break rag.ask(user_question)第三步创建启动脚本创建main.py作为更友好的入口from rag_pipeline import RAGSystem import os def main(): print( 本地知识库问答系统 ) data_dir ./data files [f for f in os.listdir(data_dir) if f.endswith((.pdf, .txt))] if not files: print(f请在 {data_dir} 目录下放置 .pdf 或 .txt 格式的知识文件。) return print(f检测到知识文件{files}) # 这里简单选择第一个文件实际可以做成选择菜单 selected_file files[0] data_path os.path.join(data_dir, selected_file) print(f\n正在基于文件 {selected_file} 初始化系统...) rag RAGSystem(data_pathdata_path) try: rag.initialize(force_recreateFalse) # 首次运行后后续可快速加载 except Exception as e: print(f初始化失败{e}) print(请检查1. API密钥是否正确 2. 文档路径是否存在 3. 网络连接) return print(\n系统准备就绪现在你可以开始提问了。) print(输入 quit 或 exit 退出程序。) print(- * 40) while True: question input(\n你的问题).strip() if question.lower() in [quit, exit]: print(再见) break if not question: continue try: rag.ask(question) except Exception as e: print(f出错了{e}) if __name__ __main__: main()5.3 运行与测试确保你的data文件夹下有文档例如一个关于某个产品说明的PDF。在rag_demo目录下激活虚拟环境并安装依赖。运行主程序python main.py首次运行会花费一些时间进行文档读取、分割和向量化Embedding API调用。完成后会在目录下生成chroma_db文件夹存储向量数据。之后再次运行系统会直接加载已有的向量数据库速度很快。尝试提问例如文档是关于“Python编程规范”的你可以问“代码注释应该遵循什么原则”系统会从文档中检索相关信息并生成回答。6. 进阶探索从RAG到智能体在掌握了RAG之后你可以向更前沿的智能体应用迈进。智能体不仅能查询知识还能主动使用工具如搜索网络、执行代码、操作数据库来完成复杂任务。6.1 智能体核心概念一个简单的智能体通常包含以下循环感知接收用户指令或环境信息。规划大模型分析任务决定下一步该做什么调用哪个工具、传递什么参数。执行调用选定的工具并获取结果。反思根据工具返回的结果判断任务是否完成若未完成则继续规划下一步。6.2 使用LangChain构建简单计算智能体下面是一个极简示例展示如何让大模型调用一个Python计算器工具。创建文件simple_agent.pyfrom langchain.agents import Tool, AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate from dotenv import load_dotenv import os import math load_dotenv() # 1. 定义工具函数 def calculator(query: str) - str: 一个简单的计算器工具能处理基本算术和math库函数。 try: # 安全考虑移除可能危险的函数仅允许安全操作 # 这里做简单演示实际生产环境需严格限制 safe_dict {math: math} # 尝试直接计算表达式 result eval(query, {__builtins__: {}}, safe_dict) return str(result) except Exception as e: return f计算错误{e}。请检查输入格式例如‘3 5 * 2’ 或 ‘math.sqrt(16)’。 # 2. 将函数封装成LangChain Tool对象 tools [ Tool( nameCalculator, funccalculator, description用于执行数学计算。输入应该是一个数学表达式字符串。 例如‘3 5 * 2’, ‘math.sqrt(16)’, ‘math.log(100, 10)’。 支持 , -, *, /, ** 运算符和 math 模块中的常见函数。 ) ] # 3. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY)) # 4. 使用ReAct框架创建智能体 # ReAct提示模板鼓励模型进行“推理”和“行动” react_prompt PromptTemplate.from_template( 你是一个智能助手可以调用工具来解决问题。 你可以使用的工具如下 {tools} 请严格按照以下格式回答 思考你需要先思考当前问题并决定是否需要使用工具以及使用哪个工具。 行动你需要调用的工具名称必须是以下之一[{tool_names}] 行动输入调用该工具所需的输入 观察工具返回的结果 ... (这个“思考/行动/行动输入/观察”循环可以重复多次) 思考我现在有最终答案了 最终答案给用户的最终答案 现在开始 问题{input} {agent_scratchpad} ) # 5. 创建智能体 agent create_react_agent(llm, tools, react_prompt) # 6. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 7. 运行智能体 if __name__ __main__: questions [ 3的4次方是多少, 计算圆周率乘以10的平方然后开根号。, 我有一个复杂的计算先计算 (15 7) * 3再将结果除以 11。 ] for q in questions: print(f\n{*50}) print(f用户问题{q}) print(f{*50}) result agent_executor.invoke({input: q}) print(f\n最终答案{result[output]})运行这个脚本你会看到智能体的思考过程它先“思考”需要计算然后“行动”调用Calculator工具传入计算表达式获得“观察”结果最后给出“最终答案”。verboseTrue参数让这个过程可视化。7. 部署与上线让应用服务化开发完成的RAG系统或智能体最终需要以API或Web服务的形式提供出去。这里我们使用FastAPI将其包装成一个简单的Web服务。在rag_demo目录下创建api_server.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from rag_pipeline import RAGSystem import uvicorn import os from dotenv import load_dotenv from typing import Optional load_dotenv() app FastAPI(title智能知识库问答API, description基于RAG的本地文档问答系统) # 全局变量存储已初始化的RAG系统 rag_system: Optional[RAGSystem] None class QueryRequest(BaseModel): question: str top_k: Optional[int] 3 # 检索返回的相关片段数量 class InitRequest(BaseModel): data_path: str force_recreate: Optional[bool] False app.on_event(startup) async def startup_event(): 服务启动时可以加载默认配置这里留空由接口触发初始化 print(RAG API 服务启动。请调用 /init 接口初始化系统。) app.post(/init) async def init_system(request: InitRequest): 初始化或重新初始化RAG系统 global rag_system try: if not os.path.exists(request.data_path): raise HTTPException(status_code400, detailf文件路径不存在{request.data_path}) rag_system RAGSystem(data_pathrequest.data_path) rag_system.initialize(force_recreaterequest.force_recreate) return {message: RAG系统初始化成功, data_path: request.data_path} except Exception as e: raise HTTPException(status_code500, detailf初始化失败{str(e)}) app.post(/ask) async def ask_question(request: QueryRequest): 提问接口 global rag_system if rag_system is None: raise HTTPException(status_code400, detailRAG系统未初始化请先调用 /init 接口。) try: # 可以动态调整检索数量 if request.top_k ! rag_system.retriever.search_kwargs.get(k): rag_system.setup_retriever(krequest.top_k) rag_system.setup_chain() answer rag_system.ask(request.question) return {question: request.question, answer: answer} except Exception as e: raise HTTPException(status_code500, detailf处理问题时出错{str(e)}) app.get(/health) async def health_check(): 健康检查端点 return {status: alive, rag_initialized: rag_system is not None} if __name__ __main__: # 启动服务默认在 http://127.0.0.1:8000 uvicorn.run(app, host0.0.0.0, port8000)运行API服务python api_server.py然后你可以使用浏览器访问http://127.0.0.1:8000/docs查看自动生成的交互式API文档Swagger UI并直接在那里测试/init和/ask接口。也可以使用curl或Python的requests库进行调用import requests # 1. 初始化系统 init_resp requests.post(http://127.0.0.1:8000/init, json{ data_path: ./data/your_knowledge.pdf, force_recreate: False }) print(init_resp.json()) # 2. 提问 ask_resp requests.post(http://127.0.0.1:8000/ask, json{ question: 文档中提到的核心要点是什么, top_k: 3 }) print(ask_resp.json())至此你已经完成了一个从环境搭建、核心概念学习、Prompt工程、RAG系统开发到智能体初探和Web服务部署的完整闭环。这个项目骨架具备了良好的扩展性你可以在此基础上增加更多功能如多文档管理、对话历史、更复杂的Agent工具链等。