RAG与大模型API实战：从零搭建本地AI搜索问答工具

最近在刷短视频时，看到一个挺有意思的观点：美国人对 AI 的情绪里带着明显的担忧甚至恐惧，而国内很多用户却已经把大模型当成新型搜索引擎来用，查资料、写文案、问攻略，随手就是一个 AI 问答。评论区也在讨论“中美 AI 差距是不是越来越大了”。作为一个常年在业务里接大模型、调接口、做 AI 应用的开发者，我觉得这类话题不能只停留在口号层面，更应该从技术侧拆一拆：中美 AI 产品生态到底差在哪，普通开发者又能从这场“应用习惯差异”里学到什么。

本文不会站队，也不会输出情绪，而是从技术角度分析 AI 产品落地模式的不同，并带大家动手实现一个可以运行在本地、接近“AI 搜索引擎”体验的问答小工具。这个工具虽然是 Demo，但它覆盖了大模型 API 接入、Prompt 设计、知识检索增强、多轮对话管理等核心知识点，非常适合后端开发者入门 AI 应用开发。

读完这篇文章，你会理解为什么国内 AI 产品普遍长着一张“搜索框”的脸，也会掌握一个可复用的“检索 + 生成”应用骨架，还能避开很多接入大模型 API 时的常见坑。

1. 现象背后的技术逻辑

1.1 “把 AI 当搜索引擎用”的真实含义

国内用户对 AI 的典型使用方式，是打开一个对话框，输入问题，然后获得一段完整的答案。这种体验本质上不是“对话”，而是“搜索答案”。用户并不关心模型是 ChatGPT 还是文心一言，只关心答案能不能直接解决问题。

这种使用习惯背后的产品逻辑是：AI 充当了知识入口，而不是聊天玩具。于是国内各大应用纷纷把 AI 做成了功能组件——你在办公软件里用 AI 写周报，在电商平台里用 AI 总结评论，在短视频应用里用 AI 回答搜索词。AI 以非常低的门槛嵌入了用户的既有行为路径。

这种现象落到技术上，就是典型的“RAG + 大模型 API”架构：用户输入问题 → 系统在知识库中检索相关片段 → 把片段拼接进 Prompt → 大模型基于片段生成答案。整条链路只暴露一个输入框给用户，背后却完成了检索、匹配、生成三个环节。

1.2 “怕 AI 怕得要死”的另外一面

欧美市场对 AI 的讨论确实更多集中在风险侧：版权诉讼、深度伪造、数据隐私、模型对齐、监管合规。ChatGPT 在欧洲上线时甚至一度面临数据保护机构的暂停要求。欧盟的《人工智能法案》也给高风险 AI 系统设置了严格的义务。

这种环境下的产品形态会明显不同：企业更倾向于把 AI 收敛在受控场景中，比如代码助手、客服摘要、内部知识库问答，而不是大规模开放给 C 端用户随意使用。AI 产品的迭代速度也会相对保守，因为一旦出错，法律和舆论成本都很高。

所以在欧美围棋里看到很多“AI 伦理工程师”“模型安全研究员”的岗位需求，这不是矫情，而是合规压力驱动的真实需求。从技术栈来看，欧美团队更早引入 guardrails（护栏）设计，比如输出内容过滤、敏感词检测、模型行为约束等模块。

1.3 差异的本质：路线选择，而非单纯“差距”

与其说中美 AI 差距大，不如说是两条不同的落地路线：

对于开发者来说，真正值得学习的是两条路线各自的工程经验。国内路线告诉我们如何快速把大模型嵌入业务，欧美路线告诉我们如何让 AI 在复杂环境下依然可控。这也是后面实战部分要设计“检索增强”和“安全过滤”两个模块的原因。

2. 环境准备与版本说明

在开始写代码之前，先把开发环境梳理清楚。这个 Demo 会是一个 Python 项目，使用 FastAPI 提供 HTTP 接口，通过 OpenAI 兼容的 API 协议调用大模型接口完成问答补全。如果你使用的是国内大模型平台的 API，多数厂商也会提供 OpenAI 兼容的访问地址，直接替换配置即可，代码逻辑不用大改。

建议环境版本如下，实际上可以按本地情况调整：

Python >= 3.10 pip >= 22.0

依赖库如下：

• openai：调用大模型接口，最新版本对 OpenAI 兼容协议支持更好。
• fastapi：提供 Web 访问接口。
• uvicorn：本地启动 FastAPI 服务。
• pydantic：解析请求参数。

安装命令：

pip install openai fastapi uvicorn pydantic

项目结构规划如下：

ai-search-demo/ ├── config.py # 配置管理 ├── model_client.py # 大模型 API 统一入口 ├── retriever.py # 简单知识检索模块 ├── chatbot.py # 对话逻辑 + 检索增强问答 ├── app.py # FastAPI 接口层 ├── main.py # 命令行交互入口 └── docs/ ├── python_basics.txt └── llm_intro.txt

本文示例的模型能力以“中等参数规模商用 API”为基准，具体版本号变化较快，无法保证长期有效，所以不会写死某个版本。你只需要在config.py中配置正确的api_key和base_url即可。

需要注意，任何大模型 API 都有上下文长度限制。本文的示例会控制 Prompt 长度，不让历史对话无限膨胀，这也是长期运行这类应用时必须考虑的问题。

3. 核心概念拆解

3.1 大模型 API 是怎么工作的

大模型 API 的表面形式非常简单：你发送一组消息，模型返回一段补全文本。关键在于消息的结构。一个典型的请求包含多个角色：

• system：设定模型的角色和回答规则。
• user：用户的输入内容。
• assistant：模型历史上的回答内容，用于多轮对话。

实际开发中，新手最容易犯的错误是多轮对话不传历史消息，导致模型“失忆”。正确做法是：维护一个包含 system、user、assistant 消息的列表，每次请求都带上最近几轮，控制好 token 长度。

3.2 检索增强生成（RAG）

RAG，全称 Retrieval-Augmented Generation，也就是检索增强生成。传统大模型只能依靠训练时学到的知识回答，但训练语料有截止时间，且无法覆盖企业的私有数据。RAG 的思路是在模型回答之前，先从外部知识库中检索出相关片段，再把片段放入 Prompt，让模型基于这些片段生成答案。

这样做的好处很明显：答案有依据、数据能实时更新、企业私有知识也能被模型使用。缺点是 Prompt 变长、系统多一个检索环节，调试起来更复杂。

在本文的 Demo 中，我会用一个小型本地文档库演示检索过程。生产环境中，这一步通常用向量数据库（比如 Milvus、Elasticsearch、pgvector）完成，内部原理相似。

3.3 “搜索引擎式 AI”的完整链路

一个接近搜索引擎体验的 AI 应用，链路如下：

1. 用户输入问题。
2. 系统分析问题，判断是需要实时检索、内部知识、还是直接闲聊。
3. 如果需要知识，从文档库或搜索引擎 API 中获取相关片段。
4. 将检索结果结构化拼装进 Prompt。
5. 大模型生成最终答案，并在答案中尽量引用来源。
6. 返回给用户，同时保留对话历史。

国内很多 AI 搜索产品，本质上就是把这个链路做得更顺畅，并且在背后接入多种数据源。开发者自己实现时，可以先从一个本地文档库开始。

4. 完整实战：搭建一个本地 AI 搜索问答工具

接下来我们进入实战部分。整个项目会拆成 5 个文件，思路是“先有一个能跑通的最小系统，再逐步加功能”。你可以边读边把代码复制到本地对应的文件中。

4.1 编写配置文件

先创建config.py，把容易变动的配置集中管理。大模型的 API 地址和模型名需要根据你实际使用的平台调整，不要照搬。

# 文件路径：ai-search-demo/config.py import os # 从环境变量读取 API Key，避免写死在代码里 API_KEY = os.getenv("LLM_API_KEY", "your-api-key") BASE_URL = os.getenv("LLM_BASE_URL", "https://api.openai.com/v1") MODEL_NAME = os.getenv("LLM_MODEL_NAME", "gpt-3.5-turbo") # 上下文最大轮数，避免历史对话无限膨胀 MAX_HISTORY_LEN = 6 # 检索最多的文档片段数 TOP_K_DOCS = 3

这里把 API Key 放到环境变量里是工程习惯。代码仓库通常是不允许提交真实密钥的，在本地实验时临时写在代码里可以，但生产项目一律用环境变量或密钥管理服务。

4.2 编写大模型客户端

model_client.py负责封装大模型调用的细节，业务层不直接接触 openai SDK。这样以后换了模型服务商，只需要改一个文件。

# 文件路径：ai-search-demo/model_client.py from openai import OpenAI import config _client = OpenAI( api_key=config.API_KEY, base_url=config.BASE_URL, ) def chat_completion(messages, temperature=0.3): """ 调用大模型接口，返回回答文本。 messages 的结构形如： [ {"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}, ] """ resp = _client.chat.completions.create( model=config.MODEL_NAME, messages=messages, temperature=temperature, ) return resp.choices[0].message.content

temperature 参数控制随机性。搜索问答类场景一般设置低一些，比如 0.2 到 0.4，让输出更加稳定、忠实于参考材料；如果是创意写作场景，可以设成 0.8 以上。

4.3 编写知识检索器

retriever.py负责在文档库里找和问题最相关的片段。生产环境一般用向量检索，这里为了让你理解原理，先实现一个最简单的关键词评分检索。

# 文件路径：ai-search-demo/retriever.py import os import re from collections import Counter class SimpleRetriever: def __init__(self, docs_dir="docs"): self.docs = [] self.load_docs(docs_dir) def load_docs(self, docs_dir): """把 docs 目录下的 txt 文件都读入内存，按空行分割成片段。""" for fname in os.listdir(docs_dir): if not fname.endswith(".txt"): continue fpath = os.path.join(docs_dir, fname) with open(fpath, "r", encoding="utf-8") as f: content = f.read() # 按空行把长文本切片，每片作为独立候选文档 blocks = [b.strip() for b in re.split(r"\n\s*\n", content) if b.strip()] self.docs.extend(blocks) @staticmethod def score(query, doc): """计算 query 和 doc 的重合关键词得分。""" query_tokens = set(query.lower().split()) doc_tokens = set(doc.lower().split()) overlap = query_tokens & doc_tokens return len(overlap) def search(self, query, top_k=3): """返回和 query 最相关的 top_k 个片段。""" scored = [(self.score(query, doc), doc) for doc in self.docs] scored.sort(key=lambda x: x[0], reverse=True) results = [doc for score, doc in scored[:top_k] if score > 0] return results

这个实现只是个基准。你可以发现它的问题：只做简单分词，不处理同义词，没有语义理解。生产环境用向量检索就是为解决这些问题。不过，用这个小工具跑通理解链路完全没有问题。

4.4 编写对话逻辑

chatbot.py是整个应用的核心。它负责组装 Prompt，并决定什么时候把检索结果拼进去。这里有一个重要的设计判断：并不是所有问题都需要检索。如果用户只是寒暄或明确要求总结，检索反而会引入噪声。所以需要一个简单的路由逻辑。

# 文件路径：ai-search-demo/chatbot.py import model_client import config from retriever import SimpleRetriever retriever = SimpleRetriever(docs_dir="docs") SYSTEM_PROMPT = """你是知识助手。如果你获得了参考资料，请优先基于资料回答，并尽量复述资料中的关键信息。如果资料不足，请直接说“根据现有资料无法回答”。回答要简洁，不要编造事实。""" def should_search(query: str) -> bool: """简单判断：问题以疑问词开头或包含知识类关键词时，触发检索。""" search_keywords = ["是什么", "怎么样", "如何", "为什么", "区别", "介绍", "原理"] return any(k in query for k in search_keywords) def build_ranked_answer(query: str) -> str: """检索资料 + 大模型生成回答。""" docs = retriever.search(query, top_k=config.TOP_K_DOCS) if not docs: return model_client.chat_completion( [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": query}, ] ) context = "\n\n---\n\n".join(docs) user_content = f"用户提问：{query}\n\n参考资料：\n{context}\n\n请基于参考资料回答。" return model_client.chat_completion( [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_content}, ] ) def chat_once(history, query: str): """处理一轮对话，返回新的问答内容和更新后的历史。""" if should_search(query): answer = build_ranked_answer(query) else: answer = model_client.chat_completion( [ {"role": "system", "content": SYSTEM_PROMPT}, *history[-config.MAX_HISTORY_LEN:], {"role": "user", "content": query}, ] ) history.append({"role": "user", "content": query}) history.append({"role": "assistant", "content": answer}) # 控制历史长度，避免超出上下文窗口 history = history[-config.MAX_HISTORY_LEN:] return history, answer

这个设计里，should_search是一个很粗糙的路由逻辑。生产环境中，你可以用一个更小的分类模型，或者让主模型自己做判断。Demo 阶段，规则也能勉强胜任。

4.5 编写命令行入口

main.py让你在终端直接体验对话效果：

# 文件路径：ai-search-demo/main.py import chatbot history = [] print("AI 知识问答助手已启动，输入 exit 退出。") while True: query = input("\n你：") if query.lower() in ("exit", "quit"): break history, answer = chatbot.chat_once(history, query) print(f"\nAI：{answer}")

运行方式：

python main.py

4.6 添加 FastAPI 接口

为了让工具更像个“产品”，再用 FastAPI 包一层 HTTP 接口，这样前端、小程序、其他后端服务都能通过统一接口调用。

# 文件路径：ai-search-demo/app.py from fastapi import FastAPI from pydantic import BaseModel, Field import chatbot app = FastAPI(title="AI Search Demo") class ChatRequest(BaseModel): query: str = Field(..., min_length=1, description="用户问题") class ChatResponse(BaseModel): answer: str history: list @app.post("/ask", response_model=ChatResponse) def ask(req: ChatRequest): # 简化处理：每次请求是独立会话，不带持久化历史 history = [] _, answer = chatbot.chat_once(history, req.query) return ChatResponse(answer=answer, history=history)

启动服务：

uvicorn app:app --reload --port 8000

然后你可以直接把下面的 JSON 请求发到http://localhost:8000/ask：

curl -X POST http://localhost:8000/ask \ -H "Content-Type: application/json" \ -d '{"query": "什么是检索增强生成？"}'

返回格式大概如下：

{ "answer": "检索增强生成（RAG）是一种让大模型在回答前先从外部知识库检索片段、并基于片段生成答案的技术方案。", "history": [] }

5. 常见问题与排查思路

接入大模型 API 和构建检索问答系统时，有几个高频问题，这里整理成表格：

5.1 接口返回 401 的排查流程

这个错误最常见。先确认你用的 Key 是否正确，再看是不是在环境变量中引号导致空格。检查方式：

# 先在终端打印，确认没有多余隐藏字符 python -c "import os; print(repr(os.getenv('LLM_API_KEY','')))"

如果输出里能找到空格或换行，就是配置文件的引号问题。另外，有些平台的 Key 开通后需要几分钟生效，遇到 401 时可以稍等片刻再试。

5.2 答非所问的调试思路

答非所问通常不是模型笨，而是 Prompt 没有束缚住。第一个调试方向是修改 system 指令，加入“你必须基于参考资料回答，资料里没有要明确说明”。第二个方向是检查检索器返回的片段是否与问题相关。你可以单独把检索结果打印出来看看：

from retriever import SimpleRetriever r = SimpleRetriever() print(r.search("什么是RAG", top_k=3))

如果检索结果本身不相关，后面模型再聪明也没用，问题在检索模块而不在生成模块。

5.3 成本与超时优化

真实项目中，大模型 API 是按 token 计费的，长时间多轮对话消耗非常快。常见优化手段：

• 对历史消息做摘要压缩，而不是全部保留。
• 检索片段做去重和截断，只保留核心信息。
• 简单问题直接走轻量模型，复杂问题才走强模型。
• 启用流式返回，减少用户等待焦虑。

6. 最佳实践与工程建议

前面代码能跑通，但离生产可用的 AI 搜索产品还有一段距离。这一节我们重点讨论工程化改造方向。

6.1 用向量检索替代关键词检索

简单的关键词匹配无法解决同义改写问题。用户问“大模型是什么”，你可能检索不到“LLM”相关资料。生产环境建议使用向量数据库，基本做法如下：

1. 对文档片段做嵌入（Embedding），得到向量并存入向量库。
2. 用户提问时也对问题做嵌入。
3. 用余弦相似度检索 Top K 向量，取对应原文片段。
4. 把片段拼入 Prompt。

嵌入模型可以选择开源模型或厂商 API。这一步改造后，检索质量会有质的提升。

6.2 Prompt 要像代码一样被管理

很多团队把 Prompt 散落在业务代码中，改了一个 Prompt 还要翻代码仓库。更好的做法是：

• 把 Prompt 模板抽取到独立配置文件或 Prompt 管理平台。
• 为不同场景建立不同 Prompt，比如知识问答、闲聊、内容总结。
• 对 Prompt 版本做记录，方便 AB 测试和回滚。

6.3 做好安全与内容合规

这是所有 AI 产品都必须重视的一环。特别是面向 C 端用户时，大模型输出的内容必须要过一道安全过滤：

• 输入侧：识别恶意请求、试图让模型突破系统指令的行为。
• 输出侧：检测色情、暴力、违法信息、个人隐私泄露等风险。
• 合规侧：按照所在地区的法律法规，对深度合成内容进行标识。

即使是最小 Demo，也应该在代码层级保留过滤入口。安全意识比安全工具更重要，在生成内容已经接触用户之后再补救，成本和风险都更高。

6.4 记录日志，为线上问题留证据

AI 应用调试难度远高于普通后端应用，因为同一个问题模型可能给出不同答案。必要日志至少包括：

• 用户输入原文。
• Prompt 最终拼装结果。
• 检索命中的文档片段 ID。
• 模型输出原文。
• 温度和模型版本标识。
• 调用耗时和 token 消耗。

日志尽量结构化，方便后续做数据分析和问题追踪。

6.5 模型选型要分场景

不要所有需求都用同一个模型。按任务难度做分级：

• 简单分类、抽取关键词：可以用小模型，成本低、响应快。
• 知识问答：中等模型即可，配合检索增强。
• 复杂推理、长文撰写：用强模型，但必须控制 Prompt 长度。

模型选型是架构问题，不是越贵越好。把合适的任务交给合适的模型，性能和成本都能得到优化。

7. 总结：把 AI 当基础设施来用

回到开头那个话题。国内 AI 产品更像一种效率工具，贴身解决用户眼前的搜索与信息整合需求；欧美 AI 产品则更强调风险治理和控制边界。两种路线各有取舍，并不存在谁“全盘领先”。

对开发者来说，最大的收益是同时借鉴两条路线的经验：用国内产品的高效落地思路快速做产品，同时把欧美团队常用的安全护栏、合规审计思路内置到系统里。这样你的 AI 应用既跑得快，又不会失控。

本文的实战部分已经帮你搭建了一个最小可用的 AI 知识问答助手。建议你上手去换一批自己的文档，比如把团队 Wiki、工作笔记放进去，感受一下“检索增强 + 大模型”和“裸调大模型”之间的差别。你的代码可以跑通之后，下一步再去研究向量检索、流式输出、安全过滤和性能优化，这些都是 AI 应用开发里真实存在的高价值技能。

如果这篇文章对你有帮助，欢迎收藏备用，也欢迎在评论区聊聊你工作中遇到的 AI 应用问题。