400行代码构建AI搜索引擎：RAG原理与Python实现详解

1. 项目概述一个极简AI搜索引擎的诞生最近在GitHub上闲逛发现一个挺有意思的项目标题就叫“400行核心代码完成整个流程”。点进去一看好家伙是一个用Python实现的AI搜索原型。作者声称只用了几百行代码就把从用户输入到AI生成答案的完整搜索流程给跑通了。这让我这个老码农瞬间来了兴趣——现在动辄谈大模型、谈Agent、谈复杂架构一个真正能跑起来的、核心逻辑清晰的最小可行产品MVP反而更有学习价值。这个项目的核心思路我把它叫做“传统搜索AI理解”的缝合怪。它没有自己去爬全网数据建索引那太重量级了而是巧妙地站在了巨人的肩膀上利用现有的搜索引擎API比如Bing Search来获取原始网页信息然后调用大语言模型LLM的API比如OpenAI的GPT或者开源的Claude Code来阅读、理解和总结这些信息最后生成一个直接、连贯的答案给用户。整个过程从接收查询、调用搜索、处理结果、请求AI到格式化输出主要的控制逻辑和数据处理真的被浓缩在了大约400行Python代码里。这解决了什么问题你想啊传统的搜索引擎给你的是十条蓝色链接你需要自己点进去在广告和无关内容里大海捞针拼凑答案。而这个AI搜索理想状态下是直接给你一个整理好的、有引用的摘要。它适合谁呢我觉得三类人最应该看看一是想快速理解AI应用落地的开发者看看一个核心流程是如何串起来的二是对RAG检索增强生成感兴趣的新手这是一个绝佳的、无干扰的入门示例三是那些被各种复杂框架搞得头晕想回归代码本质看看“引擎盖下面”到底是什么样子的技术爱好者。接下来我就带你一起拆开这个“小盒子”看看它到底是怎么转起来的。2. 核心架构与设计思路拆解2.1 为什么是“搜索LLM”的架构这个项目的设计选择非常务实它没有重新发明轮子。自己构建一个全网搜索引擎涉及爬虫、索引、排名等是一个庞大的工程。而利用现成的搜索API瞬间就获得了高质量、实时、海量的信息检索能力。这一步负责“广撒网”确保信息源的覆盖面。但是搜索API返回的是原始HTML片段、标题和摘要信息是碎片化的、未经加工的。这时候LLM的优势就体现出来了。现代的大语言模型在理解自然语言、总结归纳、逻辑推理方面表现出色。让它来扮演“信息助理”的角色阅读搜索返回的多个网页内容提取关键信息去重、比对、综合最后用人类友好的语言组织成答案。这一步负责“精加工”提升信息的可用性和可读性。这种架构的本质是**检索增强生成RAG**的一个非常直观的体现。RAG的核心思想就是当模型自身知识不足或需要最新信息时先从外部知识库这里就是互联网检索相关文档然后将这些文档作为上下文让模型生成答案。这个项目就是一个最简化的RAG系统外部知识库 搜索引擎检索器 搜索API调用生成器 LLM API调用。2.2 400行代码的模块化分解别看只有400行该有的模块一个不少结构清晰。我们可以把它大致分解成五个核心部分查询接收与预处理模块负责接收用户的自然语言问题。这里可能会做一些简单的清洗比如去除首尾空格但更关键的是它决定了是否要触发搜索。对于一些非常通用、模型自身知识足以应对的问题比如“中国的首都是哪里”理论上可以不搜索直接回答以节省成本。但这个简易项目通常默认所有查询都需要搜索。搜索引擎交互模块这是连接外部世界的桥梁。代码里会封装对某个搜索API如Bing Web Search API的调用。需要处理API密钥的配置、构造符合规范的请求URL包含查询词、结果数量、语言等参数、发送HTTP请求并解析返回的JSON或XML格式的数据提取出每个结果的标题、链接和摘要片段snippet。内容获取与清洗模块搜索引擎返回的摘要往往很短可能不足以让AI充分理解。因此一个更完善的步骤是根据上一步得到的链接再去抓取这些网页的正文内容。这里会用到像requests和BeautifulSoup这样的库。代码需要处理网络请求超时、HTML解析、剔除广告、导航栏、脚本等噪音提取出核心的文章正文。这一步对最终答案的质量影响巨大。LLM处理与答案生成模块这是AI魔法发生的地方。代码会把用户的原始问题连同从各个网页清洗、截取后的正文片段作为上下文一起构造成一个提示词Prompt发送给LLM API例如OpenAI的ChatCompletion。提示词的设计是关键例如“请基于以下提供的网页内容回答用户的问题。如果内容不足以回答请说明。请以清晰、有条理的方式总结答案并注明信息来源于哪个链接。网页内容[内容1]... [内容2]... 用户问题[用户问题]”。结果呈现与后处理模块接收LLM返回的文本答案。这里可能需要对答案进行简单的格式化比如确保引用的链接是可点击的或者将答案嵌入到一个更友好的用户界面如果是Web应用的话。在命令行版本中可能就是直接打印出来。这五个模块像流水线一样工作数据用户问题、搜索结果、网页内容、AI答案依次流过最终交付结果。400行代码要完成这些意味着每个模块的实现都必须极其精炼没有冗余错误处理也可能相对基础但这正是其作为学习范本的魅力所在——它展示了最核心的骨架。3. 关键技术细节与代码实现要点3.1 搜索引擎API的选择与调用项目通常会选择Bing Web Search API或Google Custom Search JSON API作为搜索源。以Bing为例你需要在Azure门户上创建一个资源获取API密钥。import requests def bing_search(query, api_key, count10): 调用Bing Web Search API endpoint https://api.bing.microsoft.com/v7.0/search headers {Ocp-Apim-Subscription-Key: api_key} params { q: query, count: count, # 获取的结果数量 responseFilter: Webpages, # 只要网页结果 textDecorations: False, textFormat: HTML } try: response requests.get(endpoint, headersheaders, paramsparams) response.raise_for_status() # 检查HTTP错误 search_results response.json() # 解析结果提取标题、URL、摘要 items search_results.get(webPages, {}).get(value, []) simplified_results [] for item in items: simplified_results.append({ title: item.get(name), link: item.get(url), snippet: item.get(snippet) }) return simplified_results except requests.exceptions.RequestException as e: print(f搜索请求失败: {e}) return []关键点与避坑速率限制与成本免费层API有每分钟/每月的调用次数限制。在代码中应考虑加入简单的延迟如time.sleep以避免触发限制对于学习项目够用。生产环境需要更完善的队列和重试机制。错误处理网络请求可能失败API可能返回错误。上述代码使用了try-except和raise_for_status()是最基本的处理。更健壮的版本应该能区分不同类型的错误如认证失败、额度不足、网络超时并采取不同策略。结果过滤responseFilter参数很重要确保你拿到的是网页结果而不是图片、视频等。根据问题类型你也可以调整这个参数。3.2 网页内容抓取与智能清洗拿到URL列表后下一步是获取更详细的内容。直接使用requests获取HTML然后用BeautifulSoup解析。from bs4 import BeautifulSoup import re def fetch_and_clean_content(url, timeout5): 抓取并清洗网页正文内容 headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 # 模拟浏览器 } try: resp requests.get(url, headersheaders, timeouttimeout) resp.raise_for_status() # 检查内容类型避免处理PDF、图片等 content_type resp.headers.get(content-type, ) if text/html not in content_type: return f[非HTML内容: {content_type}] soup BeautifulSoup(resp.content, html.parser) # 移除脚本、样式等无关标签 for script in soup([script, style, nav, header, footer, aside]): script.decompose() # 尝试寻找主内容区域常见标签 main_content soup.find(article) or soup.find(main) or soup.find(div, class_re.compile(r(content|post|article), re.I)) if main_content: text main_content.get_text(separator , stripTrue) else: # 保底策略获取整个body的文本 text soup.body.get_text(separator , stripTrue) if soup.body else # 简化空白字符 text re.sub(r\s, , text) # 截取前N个字符避免上下文过长LLM有token限制 max_length 3000 return text[:max_length] (... if len(text) max_length else ) except Exception as e: print(f抓取 {url} 失败: {e}) return 实操心得设置超时和User-Agent这是网络请求的基本礼仪防止程序僵死也让目标网站更容易接受请求。内容类型检查不是所有链接都是HTML可能是PDF、图片或视频。提前过滤掉能避免解析错误。精准定位正文直接获取body的文本会包含大量导航、广告、版权声明等噪音。优先寻找article,main或带有content/post类名的div标签能显著提升内容质量。这是一个经验性的规则对大多数新闻、博客网站有效。文本截断LLM API如GPT-3.5/4有上下文长度限制例如4096或更大token。一个网页的全文可能很长需要截断。更高级的做法是使用文本分割器如langchain的RecursiveCharacterTextSplitter将长文本分成有重叠的片段但这超出了400行代码的极简范畴这里简单按字符截断是一个妥协。异步抓取顺序抓取10个网页会很慢。在实际项目中强烈建议使用asyncio和aiohttp进行异步并发抓取可以大幅缩短等待时间。这在400行版本里可能被省略以保持简单。3.3 提示词工程如何与LLM高效对话这是决定答案质量的核心。你需要给LLM清晰的指令和充足的上下文。def construct_prompt(user_query, search_contexts): 构造发送给LLM的提示词 search_contexts: 列表每个元素是一个字典包含‘title’, ‘link’, ‘content’ context_str for idx, ctx in enumerate(search_contexts): # 将每个网页的内容片段用明显标记分隔开并附上来源 context_str f[来源 {idx1}: {ctx[title]} | {ctx[link]}]\n context_str f{ctx[content]}\n\n prompt f你是一个专业的AI信息助理。请严格根据用户提供的以下网络搜索内容来回答问题。 如果提供的内容中包含答案请进行综合、总结并用清晰有条理的方式输出。 如果提供的内容不足以完全回答问题请基于已有信息给出部分答案并明确指出信息的局限性。 请在回答的最后以“参考来源”开头列出你所依据的网页标题和链接。 网络搜索内容 {context_str} 用户问题{user_query} 请开始你的回答 return prompt设计要点角色设定开头明确AI的角色让它进入状态。指令清晰告诉AI“严格根据以下内容”限制它胡乱发挥内部知识确保答案有据可查。结构化上下文给每个网页内容加上[来源 X]的标题和链接方便AI区分信息来源也便于在最终答案中引用。处理不确定性指示AI在信息不足时说明局限性这比它编造一个答案幻觉要好得多。格式化要求明确要求列出参考来源这增加了答案的可信度和可验证性。一个常见的陷阱是上下文过长。如果你抓取了10个网页每个截取3000字总上下文可能远超模型限制。因此需要对search_contexts进行筛选。一个简单的策略是只保留与用户查询最相关的几个结果。可以用查询与每个网页摘要的简单文本相似度如TF-IDF或余弦相似度来排序和筛选但这又会增加代码复杂度。在极简版本中可能只使用搜索引擎返回的前3-5个结果的摘要和抓取的部分内容。3.4 调用LLM API并解析结果以OpenAI API为例import openai def ask_llm(prompt, modelgpt-3.5-turbo): 调用OpenAI ChatCompletion API # 假设openai.api_key已在环境变量中设置 try: response openai.ChatCompletion.create( modelmodel, messages[ {role: system, content: 你是一个有帮助的AI助手根据提供的信息回答问题。}, {role: user, content: prompt} ], temperature0.2, # 较低的温度让输出更确定、更基于事实 max_tokens1500 # 控制回答长度 ) answer response.choices[0].message.content return answer.strip() except openai.error.OpenAIError as e: print(fLLM API调用错误: {e}) return f抱歉AI服务暂时不可用。错误信息{e}参数解析temperature控制输出的随机性。设为较低值如0.1-0.3答案更倾向于选择最可能的词更稳定、更基于事实适合这种信息总结任务。设为较高值如0.8-1.0则更有创造性。max_tokens限制生成答案的最大长度防止生成过长内容消耗过多token。system message这里设定了助手的整体行为倾向可以与prompt中的指令互补。注意使用任何LLM API都会产生费用。OpenAI按token计费。在开发测试阶段务必关注你的用量和成本可以为API密钥设置使用额度限制。4. 完整流程串联与核心代码剖析现在我们把所有模块像拼图一样组合起来看看这400行代码的骨架是如何运作的。为了更贴近实际我们假设一个稍微优化过的流程它依然是简洁的但包含了必要的错误处理。4.1 主控制流程的实现主函数main或一个类的方法answer_question会串联起整个流程。下面是一个逻辑清晰的伪代码式描述你可以很容易地将其转化为具体代码# 伪代码/流程描述 def answer_question(user_query, search_api_key, llm_api_key, num_search_results5): 回答用户问题的完整流程 # 1. 配置API密钥 openai.api_key llm_api_key # 2. 调用搜索引擎 print(f“正在搜索{user_query}”) search_items bing_search(user_query, search_api_key, countnum_search_results) if not search_items: return “未能从搜索引擎获取到相关信息。” # 3. 并发抓取网页内容 (简化版这里用循环示意实际应用建议异步) contexts [] for item in search_items[:3]: # 只处理前3个结果以控制上下文长度 print(f“抓取内容{item[‘title’]}”) cleaned_content fetch_and_clean_content(item[‘link’]) if cleaned_content: # 只添加成功抓取的内容 contexts.append({ ‘title’: item[‘title’], ‘link’: item[‘link’], ‘content’: cleaned_content }) if not contexts: return “相关网页内容抓取失败无法生成答案。” # 4. 构造LLM提示词 prompt construct_prompt(user_query, contexts) # 5. 调用LLM生成答案 print(“正在由AI分析并生成答案...”) final_answer ask_llm(prompt) # 6. 返回最终答案 return final_answer这个流程清晰体现了“检索-增强-生成”的链条。它做了几个关键的简化第一它没有复杂的查询重写或扩展第二内容抓取是同步且可能较慢的第三它没有对抓取的内容进行深入的重新排序或相关性精筛。但正是这些简化让我们聚焦于最核心的链路。4.2 代码中的精妙之处与权衡在有限的代码行数内作者必须做出许多权衡这些权衡点正是学习的重点同步 vs 异步为了极简和降低理解门槛代码很可能使用同步请求。这意味着抓取N个网页需要N*网络延迟的时间。这是性能上的主要牺牲。在实际应用中将其改造成异步是第一个性能优化点。错误处理的粒度400行代码中的错误处理可能是基础的try-except仅打印日志并继续或返回简单错误信息。生产系统需要更细致的处理比如重试机制、降级策略如仅使用搜索摘要当抓取失败、以及用户友好的错误提示。上下文管理的策略如何将可能很长的多个网页内容塞进LLM有限的上下文窗口极简项目可能采用“截断”策略。更优的方案是“摘要”或“选择性注入”。例如可以先让LLM对每个网页内容生成一个简短摘要然后将这些摘要而非全文作为上下文。或者使用嵌入模型计算查询与每个内容片段的相似度只注入最相关的几个片段。这些策略会显著增加代码量和复杂度。成本控制每次调用都涉及搜索API可能有少量费用和LLM API按token计费。代码中没有体现成本控制逻辑如缓存历史问答、对简单问题使用更小更便宜的模型等。这是业务化时必须考虑的问题。尽管有这些权衡这个项目成功地勾勒出了一个可工作的AI搜索原型。它证明了用少量代码集成现有强大服务以创造新价值的可行性。5. 从原型到产品可能遇到的问题与优化方向当你运行起这个400行的原型兴奋之余很快就会遇到各种现实问题。下面是我能想到的一些典型坑和对应的优化思路。5.1 常见运行问题与排查API密钥错误或额度不足现象搜索或LLM调用返回401、403或429状态码。排查首先检查环境变量或配置文件中的API密钥是否正确设置且未过期。其次登录相应平台如Azure Portal, OpenAI Dashboard查看额度使用情况和是否已超限。解决更换有效的API密钥或等待额度重置。在代码中增加更友好的错误提示如“搜索服务额度已用尽请稍后再试”。网络请求超时或失败现象requests库抛出ConnectionError,Timeout异常或抓取网页内容时长时间无响应。排查检查网络连接。目标网站可能屏蔽了你的请求检查返回状态码403/404。timeout参数可能设置过短。解决增加timeout值如10秒。为requests添加更完善的try-except区分不同异常类型。对于抓取可以设置重试机制最多2-3次并考虑使用轮换的User-Agent字符串。LLM回答质量差或“幻觉”现象AI生成的答案与提供的搜索内容无关或凭空捏造事实。排查首先检查你的prompt。是否明确指令“严格根据以下内容”提供的上下文是否足够相关和清晰上下文是否过长导致模型无法有效处理末尾的信息解决优化提示词设计加入更强烈的约束如“如果答案未在以下内容中明确提及请回答‘根据已有信息无法确定’”。减少注入的上下文数量或长度确保最相关的信息在提示词的前部。考虑使用更高性能的模型如从gpt-3.5-turbo升级到gpt-4但成本更高。程序运行缓慢现象回答一个简单问题需要十几秒甚至更久。原因主要是同步顺序抓取网页造成的。解决实施异步并发抓取。这是提升性能最有效的一步。使用asyncio和aiohttp库重写fetch_and_clean_content函数。5.2 性能、成本与质量的优化策略当你想把这个原型变得更快、更省、更好用时可以考虑以下方向优化维度问题优化策略潜在代价/复杂度性能同步抓取慢改用asyncioaiohttp异步并发抓取代码复杂度增加需要理解异步编程性能LLM API调用延迟高1. 使用流式响应streaming改善用户体验感知。2. 对答案进行缓存如基于查询的MD5哈希对相同或相似查询直接返回缓存结果。流式增加前端处理复杂度缓存需要存储和管理并处理缓存过期。成本LLM Token消耗大费用高1.内容摘要在注入上下文前先用一次便宜的LLM调用如gpt-3.5-turbo对长文本进行摘要。2.选择性上下文使用嵌入模型如OpenAI的text-embedding-ada-002计算查询与内容片段的相似度只注入最相关的片段。3.模型降级对简单、事实性问题使用更小、更便宜的模型。摘要步骤增加延迟和一次API调用嵌入模型增加额外成本和复杂度需要实现模型路由逻辑。质量答案相关性、准确性不足1.更好的检索不仅仅依赖搜索引擎可以结合自身知识库的向量检索。2.提示词优化进行A/B测试设计更有效的提示词模板。3.后处理与验证让AI在答案中引用具体来源片段甚至增加一个“事实核查”步骤让另一个AI实例验证答案与上下文的一致性。向量检索需要搭建和维护向量数据库提示词工程是持续过程后处理进一步增加延迟和成本。可靠性单一API依赖风险为搜索和LLM设置备用供应商如搜索备用GoogleLLM备用Anthropic Claude或开源模型API。需要集成多套API并处理不同的请求格式和错误码。5.3 安全与合规考量即使是一个学习项目也需要有基本的安全意识API密钥管理绝对不要将API密钥硬编码在代码中或上传到GitHub。使用环境变量如os.getenv(“BING_API_KEY”)或配置文件并通过.gitignore确保配置文件不被提交。用户输入净化对用户的查询user_query进行基本的检查防止注入攻击。虽然在这个架构中查询是传递给受信任的第三方API但良好的习惯是过滤掉异常长的字符串或某些特殊字符。内容过滤搜索引擎可能返回不良或敏感信息。LLM在生成答案时可能会复现或总结这些内容。对于生产系统需要考虑在最终输出前加入内容安全过滤层。版权与引用项目生成的答案基于第三方网页内容。在呈现答案时明确标注信息来源链接不仅是良好的实践也在一定程度上尊重了内容版权。避免直接大段复制原文而是以总结和释义为主。6. 扩展思考超越400行代码的可能性这个400行的项目是一个完美的起点。理解了它的核心之后你可以像搭积木一样在各个方向上扩展它使其成为一个真正强大、可用的工具。方向一打造本地化与离线版本依赖外部API总有网络、成本和隐私的顾虑。你可以尝试替换搜索引擎使用开源的全文搜索引擎库如Whoosh纯Python或Elasticsearch索引你自己的文档集如公司内部wiki、个人笔记构建一个私域AI搜索。替换LLM使用本地部署的开源大模型如通过Ollama运行Llama 3、Qwen或Gemma。这样数据完全不出本地隐私性最强但需要较强的本地算力GPU。方向二引入更先进的RAG技术当前的流程是“一次性检索生成”。更高级的RAG模式包括迭代检索让AI根据初步检索结果自己提出新的、更精准的搜索查询进行多轮检索就像一个人在做研究时不断调整搜索关键词一样。智能排序与过滤不仅仅依赖搜索引擎的排名使用交叉编码器cross-encoder对检索到的文档进行更精细的相关性重排。HyDE假设性文档嵌入先让LLM根据问题生成一个“假设的理想答案”然后用这个假设答案去进行向量检索有时能获得更相关的结果。方向三从问答到复杂Agent这个项目本质是一个问答系统。你可以赋予它更多的能力使其成为一个AI Agent工具调用除了搜索还可以集成其他工具如计算器、天气查询、数据库查询等。让LLM根据用户问题决定调用哪个工具。记忆与多轮对话保存对话历史让AI能理解上下文进行连贯的多轮交互。规划与执行对于复杂任务如“帮我规划一个三天的北京旅游行程”让AI先制定一个计划搜索景点、评估距离、安排时间然后逐步执行搜索和生成。这个小小的400行项目就像一颗种子。它向你展示了AI应用开发中最核心的“检索-生成”范式。通过拆解它、运行它、优化它你不仅能学到如何调用API更能深刻理解数据如何在系统中流动AI如何与外部世界交互以及如何在性能、成本和质量之间做出权衡。这些经验远比直接使用一个封装好的高级框架要宝贵得多。我建议你亲手敲一遍这400行代码或者找一个类似的开源项目读一读源码遇到问题就按上面提到的思路去排查和思考这个过程本身就是最好的学习。