8-2 需求→设计→实现完整链路

本节以「智能文档问答」功能为例，完整演示一个AI功能从零到上线的全链路。这个案例真实反映了工程实践中每个阶段的核心决策点和常见坑点。

一、需求分析阶段

很多团队拿到一个模糊需求就开始写代码，这是AI项目失败的头号原因。正确的做法是先把需求分析清楚，明确以下三个维度：

1.1 明确输入输出

• 输入：用户上传的PDF/Word文档（最大50MB）+ 用户用自然语言提问
• 输出：基于文档内容的精准回答，需注明来源段落页码
• 不在范围内：图片内容识别、多轮对话历史跨文档共享

1.2 成功标准

量化指标（MVP版本目标）：
- 回答准确率 ≥ 85%（基于20题黄金测试集）
- 平均响应时间 ≤ 5秒
- 用户明确标记"有帮助"的比例 ≥ 70%
- 幻觉率（回答内容不在文档中）≤ 5%

1.3 边界条件

• 文档超过100页时如何处理（分块索引）
• 用户问的问题文档中完全没有答案时返回什么
• 多份文档同时上传时如何区分来源
• 文档包含表格/图表时的处理策略

二、系统设计阶段

2.1 技术方案选型

决策项	选项	选择理由
核心模型	GPT-4o / Claude 3.5 Sonnet	长上下文理解能力强，支持引用来源
向量数据库	Chroma / Qdrant	开源可本地部署，适合中小规模文档
文档解析	PyMuPDF + python-docx	覆盖PDF和Word两大主流格式
Embedding	text-embedding-3-small	性价比高，768维足够
框架	LangChain / LlamaIndex	RAG流程已有成熟实现，避免重复造轮子

2.2 核心Prompt设计

SYSTEM:
你是一个专业的文档问答助手。请严格基于提供的文档内容回答问题。
规则：
1. 只使用文档中明确存在的信息，不得推测或补充外部知识
2. 每个关键陈述后用[第X页]标注来源
3. 如果文档中没有相关内容，明确回答"文档中未找到相关信息"
4. 回答简洁准确，避免重复文档原文

USER:
文档内容片段：
{retrieved_chunks}

用户问题：{user_question}

请基于以上文档内容回答：

2.3 数据流设计

上传阶段：
文档上传 → 格式检测 → 文本提取 → 分块（chunk_size=512, overlap=50）
→ 批量Embedding → 存入向量数据库 → 返回文档ID

查询阶段：
用户提问 → 问题Embedding → 向量检索（Top-K=5）→ 结果重排序
→ 构建Prompt → 调用LLM → 解析输出 → 添加来源标注 → 返回用户

三、实现阶段

3.1 原型（Week 1）

目标：跑通最小闭环，不追求性能和完整性。

from langchain.document_loaders import PyMuPDFLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings
from langchain.chat_models import ChatOpenAI
from langchain.chains import RetrievalQA

# 文档加载与分块
loader = PyMuPDFLoader("document.pdf")
docs = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=512, chunk_overlap=50)
chunks = splitter.split_documents(docs)

# 构建向量索引
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(chunks, embeddings)

# 问答链
llm = ChatOpenAI(model="gpt-4o", temperature=0)
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectorstore.as_retriever(search_kwargs={"k": 5}),
    return_source_documents=True
)

result = qa_chain("这份合同的付款条件是什么？")
print(result["result"])

3.2 测试与评估（Week 2）

构建20题黄金数据集，评估准确率。发现问题：

• 长文档超过100页时检索质量下降 → 增加HyDE（假设性文档嵌入）提升检索
• 表格内容被错误分割 → 对表格单独处理，保持完整性
• 中文专业术语召回率低 → 改用中文优化的Embedding模型

3.3 迭代优化（Week 3）

# 改进：加入重排序（Reranker）提升精度
from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import CohereRerank

compressor = CohereRerank(model="rerank-multilingual-v2.0", top_n=3)
compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor,
    base_retriever=vectorstore.as_retriever(search_kwargs={"k": 10})
)
# 准确率从82%提升至89%

3.4 上线准备（Week 4）

• 添加请求限流（每用户每分钟20次）
• 接入监控：记录每次查询的响应时间、Token用量、用户反馈
• 文档缓存：相同文档不重复处理，降低API成本
• 灰度发布：先对10%用户开放，观察一周后全量

四、完整时间轴

D1-D3   需求分析 → 产出需求文档、成功标准、数据流设计
D4-D7   原型开发 → 跑通最小闭环
D8-D14  评估迭代 → 黄金数据集测试，修复主要问题
D15-D21 工程化   → 错误处理、监控、限流、缓存
D22-D28 灰度上线 → 10%流量→全量，持续收集反馈

小结

从需求到上线，每个阶段都有清晰的交付物和验收标准。AI项目最常见的错误是跳过需求分析直接进入实现，导致方向错误后推倒重来。坚持"先定义成功，再开始实现"的原则，能节省50%以上的无效工作量。