Python | 杨劲松 - Java后端 / AI应用开发工程师

FastAPI 请求与响应：用 Pydantic 建立可靠契约

Fri, 21 Aug 2026 00:00:00 +0000

上图：FastAPI — FastAPI 请求与响应。

AI 接口的输入经常来自不可信客户端，输出又可能来自不稳定的模型或第三方 API。Pydantic schema 是第一道边界：它把看起来像数据变成可验证的数据。

核心心智模型

请求模型负责输入约束，领域模型负责业务不变量，响应模型负责公开字段。不要直接返回 ORM 对象或供应商原始 JSON。

关键机制

对字符串设长度上下限，对枚举使用 Literal，对嵌套结构使用模型；对模型输出先解析再返回，解析失败走可观测的 502/422 分支。

Python 示例

from typing import Literal
from pydantic import BaseModel, Field

class ChatRequest(BaseModel):
 message: str = Field(min_length=1, max_length=4000)
 mode: Literal["answer", "summarize"] = "answer"

class ChatResponse(BaseModel):
 request_id: str
 answer: str
 citations: list[str] = Field(default_factory=list)

课程定位

这篇文章把白板上的模块拆成可以落地的工程边界：先定义输入和输出，再决定状态、失败策略与可观测性。示例使用 Python，重点是设计原则而不是绑定某个供应商版本；上线前请以当前依赖的官方文档为准。

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

先实现白板中的最小闭环，再故意注入一个超时、一个空结果和一个格式错误，观察系统能否给出稳定且可诊断的结果。最后补一条指标，证明你的优化确实改善了质量或延迟。

动手练习

为一个问答接口加入 request_id、长度限制、模式枚举和 citations。分别提交空字符串、超长文本、未知 mode 与缺失字段，确认客户端得到稳定错误。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

FastAPI 项目架构：从路由到领域服务的分层设计

Fri, 21 Aug 2026 00:00:00 +0000

上图：FastAPI — FastAPI 项目架构。

FastAPI 很容易在一个文件里快速起步，也很容易因此变成不可维护的全局脚本。更稳妥的结构是让路由处理 HTTP，让 service 处理用例，让 repository 处理数据访问。

核心心智模型

推荐的调用方向是 router → service → repository/provider，依赖通过函数参数注入。领域服务不应依赖 Request 或 HTTP 状态码，这样可以在命令行、任务队列和测试中复用。

关键机制

配置用环境变量读取并在启动时校验；连接池在 lifespan 中创建和关闭；异常统一映射为稳定的错误 schema。

Python 示例

from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter(prefix="/v1/chat", tags=["chat"])

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 answer: str

@router.post("", response_model=ChatResponse)
async def chat(req: ChatRequest, service = Depends(get_chat_service)):
 return ChatResponse(answer=await service.answer(req.message))

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

把一个包含模型调用的路由拆成 api、services、providers 和 schemas，为 service 注入 fake provider，并用 TestClient 验证错误映射。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

LangChain Prompt Chain：让提示词成为可维护的程序

Fri, 21 Aug 2026 00:00:00 +0000

上图：LangChain — LangChain Prompt Chain。

提示词不是散落在代码里的长字符串，而是一个需要版本管理、输入校验和回归测试的程序组件。本篇围绕模板、结构化输入、模型和解析建立可靠链路。

核心心智模型

稳定的 Prompt Chain 会区分 system 规则、human 任务和历史上下文；变量名应该表达语义，避免一个 text 在不同阶段含义漂移。

关键机制

先渲染并检查 prompt，再调用模型。对长上下文做长度预算，对用户文本做边界标记；不要把用户提供的内容拼进 system 指令。

Python 示例

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
 ("system", "只依据 context 回答；信息不足时明确说不知道。"),
 ("human", "<context>\n{context}\n</context>\n问题：{question}"),
])
chain = prompt | model | StrOutputParser()
print(chain.invoke({"context": "幂等请求重复执行不会产生额外业务副作用。", "question": "幂等性解决什么问题？"}))

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

给 prompt 增加 prompt_version，把 20 个固定问题作为回归集，比较每次修改前后的事实一致性、拒答率和 token 用量。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

LangChain 核心架构：Runnable、模型与可组合链

Fri, 21 Aug 2026 00:00:00 +0000

上图：LangChain — LangChain 核心架构。

LangChain 的价值不只是把模型包起来，而是提供一套可组合的运行时接口。把 prompt、model、parser 看成同一条 Runnable 管道后，调用、批处理、流式输出和追踪都可以采用一致的方式。

核心心智模型

典型链路是输入字典 → ChatPromptTemplate → ChatModel → StrOutputParser。每个节点有自己的契约，链只负责连接它们；这让模型替换和局部测试变得简单。

关键机制

组合操作符表达数据流，invoke 适合单次请求，batch 适合批量任务，stream 适合低首字节延迟。生产代码应在边界处做类型检查和超时控制，而不是把异常吞掉。

Python 示例

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是简洁的技术助手。"),
 ("human", "请用三点解释：{question}"),
])
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
chain = prompt | model | StrOutputParser()
answer = chain.invoke({"question": "什么是幂等性？"})

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

把 chain 拆成 render_prompt、call_model 和 parse_output 三个可替换阶段，并为 parser 写一个不依赖网络的测试。若将来更换模型，测试应只关心最终契约，而不是供应商响应的内部字段。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

OpenAI API 基础：请求、消息、参数与可靠性

Fri, 21 Aug 2026 00:00:00 +0000

上图：OpenAI — OpenAI API 基础。

调用模型 API 的核心不是记住一个 endpoint，而是把网络请求当作不可靠的外部依赖。请求契约、超时、错误分类和用量记录必须在第一天就设计好。

核心心智模型

请求由 system/developer 规则、user 输入和可选工具组成；模型输出只是候选结果，应用层仍需验证、过滤和持久化。

关键机制

区分 4xx 参数/权限错误、429 限流、5xx 上游故障和本地超时；只对可重试类别做带抖动的指数退避，并设置总预算。

Python 示例

import asyncio, random

async def call_with_retry(client, request, attempts=3):
 for n in range(attempts):
 try:
 return await client.responses.create(**request, timeout=20)
 except (TimeoutError, RateLimitError):
 if n == attempts - 1: raise
 await asyncio.sleep((2 ** n) + random.random())

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

为一次调用增加 request id、耗时、输入/输出 token 和错误类别日志；再用模拟 429 与 400 的 fake client 验证只有 429 会重试。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

Python AI 工程：把模型调用接入可靠应用

Fri, 21 Aug 2026 00:00:00 +0000

上图：AI Engineering with Python 白板图；重点不是罗列名词，而是把一次真实请求如何穿过系统、在哪些边界失败画清楚。

为什么要从场景理解这张图

这张图围绕“A support copilot answers only from authorized policy passages and returns a review state when evidence is weak.”展开。学习 AI Engineering with Python 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Application → Prompt / RAG / Tool → Model → Validated Result。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：FastAPI → typed request / response；Retriever → evidence + ACL filter。这些机制决定延迟、吞吐和可测试性。
资源与状态：Model call → timeout + retry budget；Tool → allowlist + argument validation。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Structured output → schema parse；必要时再结合 Trace → prompt version + cost + quality 做降级、重试或回滚。

一个可落地的最小实现

下面的片段只展示边界，不代表完整业务。它的价值在于把“可以替换、可以测试、可以观测”的位置固定下来。

result = await model.ainvoke(prompt)
answer = Answer.model_validate_json(result.content)

在真实项目中，应把外部依赖封装在 adapter 或 repository 中；业务层只依赖稳定接口。这样本地测试可以使用 fake，压测可以替换慢依赖，线上故障也更容易定位。

场景中的工程决策

以白板右侧的生产场景为例：

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 schema 校验至少要有一种明确机制，避免重试带来重复写入。
最后优化性能：先用 trace、慢查询、GC pause、队列长度、p99 延迟等数据定位，再选择索引、缓存、批处理或并发策略。
让故障可恢复：超时、重试、限流、熔断、回滚和告警必须能在演练中被验证，而不是只写在文档里。

常见误区

只画成功路径，没有画超时、空数据、拒绝、回滚或副本延迟。
把框架默认行为当成业务契约，升级依赖后才发现边界改变。
用“加机器”替代测量，忽略连接池、锁竞争、慢 SQL、对象分配或事件循环阻塞。
将日志当作唯一观测手段，缺少指标、trace、采样和敏感数据脱敏。

生产检查清单

输入、输出和错误响应有明确 schema
外部调用设置 timeout、retry 上限、rate limit 和 fallback
资源池有容量、排队和拒绝指标
关键状态有幂等、事务或恢复策略
日志、metrics、trace 可关联同一个 request id
用接近生产的数据做回归、压测和故障演练

总结

真正掌握这张白板图，不是能背出每个框的定义，而是能从一次具体请求出发，解释每个箭头的输入输出、每个风险的处置方式，以及上线后用什么信号判断系统需要改进。

Python asyncio 并发：事件循环与非阻塞 I/O

Fri, 21 Aug 2026 00:00:00 +0000

上图：Python asyncio & Concurrency 白板图；重点不是罗列名词，而是把一次真实请求如何穿过系统、在哪些边界失败画清楚。

为什么要从场景理解这张图

这张图围绕“A profile page fans out to several services while a semaphore protects the slowest dependency.”展开。学习 Python asyncio & Concurrency 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Coroutine → Event Loop → Await I/O → Gather Results。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：async def → coroutine object；create_task → scheduled work。这些机制决定延迟、吞吐和可测试性。
资源与状态：await → yield while I/O is pending；gather / TaskGroup → coordinate tasks。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Semaphore → bound downstream concurrency；必要时再结合 Cancellation + timeout → cleanup path 做降级、重试或回滚。

一个可落地的最小实现

下面的片段只展示边界，不代表完整业务。它的价值在于把“可以替换、可以测试、可以观测”的位置固定下来。

async with asyncio.TaskGroup() as group:
 for url in urls:
 group.create_task(fetch(url))

场景中的工程决策

以白板右侧的生产场景为例：

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 schema 校验至少要有一种明确机制，避免重试带来重复写入。
最后优化性能：先用 trace、慢查询、GC pause、队列长度、p99 延迟等数据定位，再选择索引、缓存、批处理或并发策略。
让故障可恢复：超时、重试、限流、熔断、回滚和告警必须能在演练中被验证，而不是只写在文档里。

常见误区

只画成功路径，没有画超时、空数据、拒绝、回滚或副本延迟。
把框架默认行为当成业务契约，升级依赖后才发现边界改变。
用“加机器”替代测量，忽略连接池、锁竞争、慢 SQL、对象分配或事件循环阻塞。
将日志当作唯一观测手段，缺少指标、trace、采样和敏感数据脱敏。

生产检查清单

输入、输出和错误响应有明确 schema
外部调用设置 timeout、retry 上限、rate limit 和 fallback
资源池有容量、排队和拒绝指标
关键状态有幂等、事务或恢复策略
日志、metrics、trace 可关联同一个 request id
用接近生产的数据做回归、压测和故障演练

总结

Python 数据结构与装饰器：复用行为而不隐藏边界

Fri, 21 Aug 2026 00:00:00 +0000

上图：Python Data Structures & Decorators 白板图；重点不是罗列名词，而是把一次真实请求如何穿过系统、在哪些边界失败画清楚。

为什么要从场景理解这张图

这张图围绕“An ETL job streams a large CSV, deduplicates IDs with a set, and wraps retries without hiding failures.”展开。学习 Python Data Structures & Decorators 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Choose the right container; wrap behavior explicitly。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：list → ordered mutable sequence；tuple → immutable record-like value。这些机制决定延迟、吞吐和可测试性。
资源与状态：dict → keyed lookup + explicit schema；set → membership / deduplication。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Decorator → wrapper preserves contract；必要时再结合 Generator → lazy iteration + bounded memory 做降级、重试或回滚。

一个可落地的最小实现

下面的片段只展示边界，不代表完整业务。它的价值在于把“可以替换、可以测试、可以观测”的位置固定下来。

from functools import wraps
def traced(fn):
 @wraps(fn)
 def wrapper(*args, **kwargs):
 return fn(*args, **kwargs)
 return wrapper

场景中的工程决策

以白板右侧的生产场景为例：

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 schema 校验至少要有一种明确机制，避免重试带来重复写入。
最后优化性能：先用 trace、慢查询、GC pause、队列长度、p99 延迟等数据定位，再选择索引、缓存、批处理或并发策略。
让故障可恢复：超时、重试、限流、熔断、回滚和告警必须能在演练中被验证，而不是只写在文档里。

常见误区

只画成功路径，没有画超时、空数据、拒绝、回滚或副本延迟。
把框架默认行为当成业务契约，升级依赖后才发现边界改变。
用“加机器”替代测量，忽略连接池、锁竞争、慢 SQL、对象分配或事件循环阻塞。
将日志当作唯一观测手段，缺少指标、trace、采样和敏感数据脱敏。

生产检查清单

输入、输出和错误响应有明确 schema
外部调用设置 timeout、retry 上限、rate limit 和 fallback
资源池有容量、排队和拒绝指标
关键状态有幂等、事务或恢复策略
日志、metrics、trace 可关联同一个 request id
用接近生产的数据做回归、压测和故障演练

总结

Python 运行时：源码、字节码与对象模型

Fri, 21 Aug 2026 00:00:00 +0000

上图：Python Runtime & Basics 白板图；重点不是罗列名词，而是把一次真实请求如何穿过系统、在哪些边界失败画清楚。

为什么要从场景理解这张图

这张图围绕“A data pipeline validates records at its boundary and uses profiling to find the real CPU hotspot.”展开。学习 Python Runtime & Basics 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Python Code → Parser → AST → Bytecode → Interpreter。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Source → tokens → AST；AST → bytecode instructions。这些机制决定延迟、吞吐和可测试性。
资源与状态：Interpreter loop executes bytecode；int / str / list / dict are objects。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Dynamic typing resolves at runtime；必要时再结合 Reference counting + cyclic GC reclaim objects 做降级、重试或回滚。

一个可落地的最小实现

下面的片段只展示边界，不代表完整业务。它的价值在于把“可以替换、可以测试、可以观测”的位置固定下来。

def total(items: list[int]) -> int:
 return sum(items)

场景中的工程决策

以白板右侧的生产场景为例：

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 schema 校验至少要有一种明确机制，避免重试带来重复写入。
最后优化性能：先用 trace、慢查询、GC pause、队列长度、p99 延迟等数据定位，再选择索引、缓存、批处理或并发策略。
让故障可恢复：超时、重试、限流、熔断、回滚和告警必须能在演练中被验证，而不是只写在文档里。

常见误区

只画成功路径，没有画超时、空数据、拒绝、回滚或副本延迟。
把框架默认行为当成业务契约，升级依赖后才发现边界改变。
用“加机器”替代测量，忽略连接池、锁竞争、慢 SQL、对象分配或事件循环阻塞。
将日志当作唯一观测手段，缺少指标、trace、采样和敏感数据脱敏。

生产检查清单

输入、输出和错误响应有明确 schema
外部调用设置 timeout、retry 上限、rate limit 和 fallback
资源池有容量、排队和拒绝指标
关键状态有幂等、事务或恢复策略
日志、metrics、trace 可关联同一个 request id
用接近生产的数据做回归、压测和故障演练

总结

RAG 基础管道：从文档到可引用答案

Fri, 21 Aug 2026 00:00:00 +0000

上图：RAG — RAG 基础管道。

RAG 不是给模型塞几段文本这么简单，而是一条知识数据管道。最终质量同时受文档解析、切分、召回、提示词和答案验证影响。

核心心智模型

离线阶段是 Load → Clean → Chunk → Embed → Index，在线阶段是 Query → Retrieve → Rerank/Filter → Generate → Cite。两条链路要用版本号连接。

关键机制

每个 chunk 保存 source、page、section 和 content hash。回答时只传递通过相关性阈值的上下文，并要求模型给出可回溯引用。

Python 示例

from dataclasses import dataclass

@dataclass
class Chunk:
 text: str
 source: str
 page: int
 chunk_id: str

def make_context(chunks: list[Chunk]) -> str:
 return "\n\n".join(f"[{c.chunk_id}] {c.text} (source={c.source}, page={c.page})" for c in chunks)

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

建立 30 个带标准答案和来源的问题，分别评估检索命中率、引用正确率和拒答准确率；不要只看模型回答是否读起来合理。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

RAG系统中的三层幻觉预防：实践指南

Wed, 05 Aug 2026 00:00:00 +0000

幻觉是部署LLM用于生产环境时最大的挑战之一。本指南介绍了一种实用的三层方法来预防RAG系统中的幻觉。

上图：RAG幻觉预防的三层防御架构 —— 检索过滤 → 提示词工程 → 输出验证

理解幻觉

幻觉是指LLM生成看似合理但事实不正确的信息。在RAG系统中，这通常发生在：

检索到的上下文不相关或不足
LLM优先使用其训练数据而非提供的上下文
模型用编造的信息"填补空白"

常见场景

产品信息 - LLM编造价格、规格或可用性
医疗/农业建议 - 生成错误的剂量或治疗方法
法律/财务 - 创建不存在的法规或政策

第一层：检索过滤

确保只有相关信息到达LLM：

from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import LLMChainExtractor

class RetrievalFilter:
 def __init__(self, vector_store, llm):
 self.vector_store = vector_store
 self.llm = llm

 def filter_documents(self, query: str, threshold: float = 0.7):
 """按相关性过滤检索到的文档。"""
 # 获取初始结果
 results = self.vector_store.similarity_search_with_score(query, k=10)

 # 按分数阈值过滤
 filtered = [
 (doc, score)
 for doc, score in results
 if score >= threshold
 ]

 # 使用LLM重新排序
 reranked = self.rerank_with_llm(query, filtered)

 return reranked

 def rerank_with_llm(self, query: str, documents):
 """使用LLM按相关性重新排序文档。"""
 prompt = f"""根据查询对这些文档按相关性排序：{query}

文档：
{[doc.page_content for doc, _ in documents]}

返回最相关的文档索引（逗号分隔）："""

 response = self.llm.predict(prompt)
 # 解析并返回顶级文档
 # 实现细节...

过滤策略

分数阈值 - 移除低相关性文档
多样性过滤 - 确保多样化的视角
来源验证 - 优先考虑权威来源
时效性过滤 - 偏好最新信息

第二层：提示词工程

设计约束LLM行为的提示词：

HALLUCINATION_PREVENTION_PROMPT = """你是一个有用的助手。仅基于提供的上下文回答问题。

规则：
1. 如果上下文没有包含足够的信息，请说"我没有足够的信息来回答这个问题。"
2. 永远不要编造上下文中不存在的信息。
3. 尽可能引用源文档。
4. 如果多个来源冲突，请呈现两种观点。
5. 对于数值数据，引用上下文中的确切数字。

上下文：
{context}

问题：{input}

回答："""

按领域的提示词模板

电商产品：

ECOMMERC_PROMPT = """你是产品专家。仅使用提供的产品信息回答产品问题。

规则：
1. 永远不要编造价格、规格或可用性
2. 如果产品信息不完整，请说"我没有关于此产品的完整信息"
3. 始终提及数据中的产品名称和关键特性
4. 对于比较，严格坚持提供的数据

产品信息：
{context}

问题：{input}
"""

农业知识：

AGRICULTURAL_PROMPT = """你是农业专家。仅使用提供的知识库回答农业问题。

规则：
1. 永远不要编造农药剂量或治疗方法
2. 如果知识库没有涵盖特定作物/病害，建议咨询当地专家
3. 尽可能引用源手册
4. 对于安全关键建议，包含适当的警告

知识库：
{context}

问题：{input}
"""

第三层：输出验证

根据源数据验证LLM响应：

import re
from typing import Dict, List, Tuple

class OutputValidator:
 def __init__(self, llm):
 self.llm = llm

 def validate_response(self, response: str, context: str) -> Dict:
 """根据源上下文验证LLM响应。"""
 validation_results = {
 "is_valid": True,
 "issues": [],
 "corrected_response": response
 }

 # 检查1：数值声明
 numerical_issues = self.check_numerical_claims(response, context)
 if numerical_issues:
 validation_results["issues"].extend(numerical_issues)

 # 检查2：实体验证
 entity_issues = self.verify_entities(response, context)
 if entity_issues:
 validation_results["issues"].extend(entity_issues)

 # 检查3：来源引用
 citation_issues = self.check_citations(response, context)
 if citation_issues:
 validation_results["issues"].extend(citation_issues)

 # 如果发现问题，生成修正后的响应
 if validation_results["issues"]:
 validation_results["corrected_response"] = self.generate_corrected_response(
 response, validation_results["issues"], context
 )
 validation_results["is_valid"] = False

 return validation_results

 def check_numerical_claims(self, response: str, context: str) -> List[str]:
 """验证响应中的数值在上下文中存在。"""
 issues = []

 # 从响应中提取数字
 numbers = re.findall(r'\b\d+(?:\.\d+)?(?:%|元|kg|ml)?\b', response)

 for number in numbers:
 if number not in context:
 issues.append(f"数值 '{number}' 在源上下文中未找到")

 return issues

 def verify_entities(self, response: str, context: str) -> List[str]:
 """验证产品/实体名称在上下文中存在。"""
 issues = []

 # 简单实体提取（可增强NER）
 entities = re.findall(r'[A-Z][a-z]+(?:\s[A-Z][a-z]+)*', response)

 for entity in entities:
 if entity.lower() not in context.lower():
 issues.append(f"实体 '{entity}' 在源上下文中未找到")

 return issues

实现示例

完整的三层预防系统：

from langchain.chains import LLMChain
from langchain.prompts import ChatPromptTemplate

class HallucinationPreventionSystem:
 def __init__(self, vector_store, llm):
 self.vector_store = vector_store
 self.llm = llm
 self.retrieval_filter = RetrievalFilter(vector_store, llm)
 self.output_validator = OutputValidator(llm)

 def query(self, user_input: str) -> Dict:
 """使用三层幻觉预防处理查询。"""

 # 第一层：过滤检索
 filtered_docs = self.retrieval_filter.filter_documents(user_input)
 context = "\n\n".join([doc.page_content for doc in filtered_docs])

 # 第二层：使用约束提示词生成响应
 prompt = ChatPromptTemplate.from_template(HALLUCINATION_PREVENTION_PROMPT)
 chain = LLMChain(llm=self.llm, prompt=prompt)
 response = chain.invoke({"context": context, "input": user_input})

 # 第三层：验证输出
 validation = self.output_validator.validate_response(
 response["text"], context
 )

 return {
 "response": validation["corrected_response"],
 "is_valid": validation["is_valid"],
 "issues": validation["issues"],
 "sources": [doc.metadata.get("source") for doc in filtered_docs]
 }

效果衡量

跟踪关键指标以评估预防系统：

class HallucinationMetrics:
 def __init__(self):
 self.metrics = {
 "total_queries": 0,
 "hallucinations_detected": 0,
 "false_positives": 0,
 "retrieval_accuracy": 0
 }

 def evaluate_response(self, response: str, context: str, ground_truth: str):
 """评估响应质量和幻觉存在情况。"""
 self.metrics["total_queries"] += 1

 # 检查幻觉
 if self.detect_hallucination(response, context):
 self.metrics["hallucinations_detected"] += 1

 # 与真实情况比较
 accuracy = self.calculate_accuracy(response, ground_truth)
 self.metrics["retrieval_accuracy"] += accuracy

 def detect_hallucination(self, response: str, context: str) -> bool:
 """简单幻觉检测。"""
 # 检查响应是否包含上下文中没有的信息
 response_words = set(response.lower().split())
 context_words = set(context.lower().split())

 # 响应中有但上下文中没有的词
 novel_words = response_words - context_words

 # 如果太多新词，可能是幻觉
 return len(novel_words) > len(response_words) * 0.3

指标仪表板

指标	描述	目标
幻觉率	包含幻觉的响应百分比	< 5%
检索准确性	检索到的相关文档百分比	> 90%
响应质量	用户满意度评分	> 4.5/5
延迟	包含验证的响应时间	< 2秒

总结

预防RAG系统中的幻觉需要多层次方法：

检索过滤 - 确保只有相关信息到达LLM
提示词工程 - 使用清晰指令约束LLM行为
输出验证 - 根据源数据验证响应

完整实现可在上获取。

有问题？通过或邮件联系我！

使用LangChain构建AI智能体：工具集成与多轮对话

Fri, 10 Jul 2026 00:00:00 +0000

AI智能体正在改变我们构建智能应用的方式。与简单聊天机器人不同，智能体可以使用工具、保持上下文并做出决策。本指南介绍如何使用LangChain构建生产级智能体。

上图：LangChain Agent架构 — 用户输入 → 推理循环 → 工具调用 → 多轮对话

什么是AI智能体？

智能体结合了LLM、工具和推理能力：

用户输入 → 智能体（推理） → 工具选择 → 工具执行 → 响应

关键特征：

工具使用 - 可与外部系统交互
推理 - 决定使用哪些工具以及何时使用
记忆 - 跨交互保持上下文
自主性 - 可以链接多个操作

LangChain智能体框架

LangChain提供了强大的智能体构建框架：

from langchain.agents import create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# 初始化LLM
llm = ChatOpenAI(model="gpt-4", temperature=0)

# 定义提示词
prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个有工具访问权限的有用助手。"),
 ("human", "{input}"),
 ("placeholder", "{agent_scratchpad}")
])

# 创建智能体
agent = create_openai_tools_agent(llm, tools, prompt)

自定义工具开发

为你的用例构建特定工具：

from langchain_core.tools import tool
from typing import Optional

@tool
def search_knowledge_base(query: str) -> str:
 """搜索私有知识库获取信息。"""
 # 实现代码
 results = vector_store.similarity_search(query, k=3)
 return "\n".join([doc.page_content for doc in results])

@tool
def get_product_info(product_id: str) -> str:
 """通过ID获取详细产品信息。"""
 # 数据库查询
 product = db.get_product(product_id)
 return f"产品: {product.name}, 价格: {product.price}"

# 注册工具
tools = [search_knowledge_base, get_product_info]

工具最佳实践

清晰描述 - 帮助智能体理解何时使用每个工具
错误处理 - 优雅处理工具失败
输入验证 - 处理前验证输入
速率限制 - 防止外部API滥用

记忆管理

实现对话记忆以保持上下文：

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

# 初始化记忆
memory = ConversationBufferMemory(return_messages=True)

# 创建对话链
conversation = ConversationChain(
 llm=llm,
 memory=memory,
 verbose=True
)

# 在智能体中使用
agent = create_openai_tools_agent(
 llm, tools, prompt,
 memory=memory
)

记忆类型

类型	用途	权衡
缓冲	简单对话	有限上下文
摘要	长对话	信息丢失
向量	语义搜索	存储开销
实体	实体跟踪	复杂性

多轮对话

处理复杂对话流程：

from langchain.agents import AgentExecutor

# 创建智能体执行器
agent_executor = AgentExecutor(
 agent=agent,
 tools=tools,
 verbose=True,
 max_iterations=10, # 防止无限循环
 handle_parsing_errors=True
)

# 带上下文的对话
def chat(user_input: str, conversation_id: str):
 # 加载对话历史
 history = load_conversation_history(conversation_id)

 # 运行智能体
 result = agent_executor.invoke({
 "input": user_input,
 "chat_history": history
 })

 # 保存到历史
 save_conversation_history(conversation_id, user_input, result["output"])

 return result["output"]

生产部署

1. FastAPI集成

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ChatRequest(BaseModel):
 message: str
 conversation_id: str

class ChatResponse(BaseModel):
 response: str
 conversation_id: str

@app.post("/chat", response_model=ChatResponse)
async def chat_endpoint(request: ChatRequest):
 try:
 response = chat(request.message, request.conversation_id)
 return ChatResponse(
 response=response,
 conversation_id=request.conversation_id
 )
 except Exception as e:
 raise HTTPException(status_code=500, detail=str(e))

2. 流式响应

from fastapi.responses import StreamingResponse

@app.post("/chat/stream")
async def chat_stream(request: ChatRequest):
 async def generate():
 async for event in agent_executor.astream_events(
 {"input": request.message},
 version="v1"
 ):
 if event["event"] == "on_chat_model_stream":
 content = event["data"]["chunk"].content
 if content:
 yield f"data: {content}\n\n"
 yield "data: [DONE]\n\n"

 return StreamingResponse(generate(), media_type="text/event-stream")

3. 错误处理

@app.middleware("http")
async def error_handler(request, call_next):
 try:
 response = await call_next(request)
 return response
 except Exception as e:
 logger.error(f"智能体错误: {e}")
 return JSONResponse(
 status_code=500,
 content={"error": "内部服务器错误"}
 )

实际案例：农业问答智能体

以下是我如何构建农业知识库智能体：

from langchain.agents import create_openai_tools_agent
from langchain.tools import Tool

# 定义农业工具
tools = [
 Tool(
 name="SearchKnowledgeBase",
 func=search_agricultural_knowledge,
 description="搜索私有农业手册获取作物病害、治疗和最佳实践"
 ),
 Tool(
 name="GeneralAgriculturalKnowledge",
 func=get_general_knowledge,
 description="当私有知识库没有答案时获取一般农业信息"
 )
]

# 强调私有数据优先的系统提示词
system_prompt = """你是一位农业专家助手。

重要提示：始终首先搜索私有知识库。仅在私有搜索没有返回相关结果时使用一般知识。

回答时：
1. 尽可能引用源文档
2. 具体说明作物名称、病害症状和治疗方法
3. 如果不确定，请说"建议咨询当地农业专家"
"""

总结

构建AI智能体需要：

工具设计 - 清晰、文档良好的工具
记忆管理 - 适合用例的记忆策略
错误处理 - 优雅的失败管理
用户体验 - 流式传输和清晰反馈

完整农业智能体代码可在上获取。

有问题？通过或邮件联系我！

使用LangChain构建RAG管道：从文档处理到向量搜索

Mon, 15 Jun 2026 00:00:00 +0000

检索增强生成（RAG）已成为构建需要访问特定知识库的AI应用的标准方法。本指南将介绍如何使用LangChain从零开始构建完整的RAG管道。

上图：Production RAG Pipeline — 文档摄入 → 向量嵌入 → 检索 → 增强生成 → 输出

什么是RAG？

RAG结合了大语言模型和外部知识检索的能力：

用户查询 → 检索 → 上下文 + 查询 → LLM → 回答

这种方法解决了LLM的核心问题：它们只能基于训练数据回答问题。RAG允许它们访问最新的、特定领域的或私有的信息。

文档处理

第一步是为检索准备文档：

from langchain.document_loaders import PyPDFLoader
from langchain.text_splitter import TokenTextSplitter

# 加载文档
loader = PyPDFLoader("knowledge_base.pdf")
documents = loader.load()

# 分割为块
text_splitter = TokenTextSplitter(
 chunk_size=500,
 chunk_overlap=50,
 encoding_name="cl100k_base" # OpenAI分词器
)

chunks = text_splitter.split_documents(documents)

关键考虑

块大小 - 平衡上下文和检索准确性
重叠 - 防止重要信息被分割到不同块中
元数据 - 保留源信息用于归属

向量存储

存储嵌入以进行高效相似性搜索：

from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Redis

# 初始化嵌入
embeddings = OpenAIEmbeddings()

# 创建向量存储
vector_store = Redis.from_documents(
 documents=chunks,
 embedding=embeddings,
 redis_url="redis://localhost:6379",
 index_name="knowledge_base"
)

选择向量存储

存储	性能	功能	最佳用途
Redis	高	实时更新	生产环境
Pinecone	高	托管服务	企业级
FAISS	中	本地、免费	开发环境
Chroma	中	简单设置	原型开发

检索策略

使用LangChain实现智能检索：

from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import LLMChainExtractor

# 基本相似性搜索
retriever = vector_store.as_retriever(
 search_type="similarity",
 search_kwargs={"k": 5}
)

# 高级：上下文压缩
compressor = LLMChainExtractor.from_llm(llm)
compression_retriever = ContextualCompressionRetriever(
 base_compressor=compressor,
 base_retriever=retriever
)

幻觉预防

对生产级RAG系统至关重要：

from langchain.prompts import ChatPromptTemplate

system_prompt = """你是一位农业专家。仅基于提供的上下文回答问题。如果上下文没有包含足够的信息，请说"我没有足够的信息来回答这个问题。"

上下文：{context}
"""

prompt = ChatPromptTemplate.from_messages([
 ("system", system_prompt),
 ("human", "{input}")
])

三层预防

检索过滤 - 仅传递高相关性文档
提示词工程 - 强制模型引用来源
输出验证 - 验证响应与源数据

流式接口

使用FastAPI实现实时响应：

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio

app = FastAPI()

@app.post("/chat")
async def chat(query: str):
 async def generate():
 async for chunk in chain.astream({"input": query}):
 yield f"data: {chunk.content}\n\n"
 await asyncio.sleep(0.01) # 模拟打字效果
 yield "data: [DONE]\n\n"

 return StreamingResponse(
 generate(),
 media_type="text/event-stream"
 )

生产环境考虑

1. 错误处理

try:
 response = await chain.ainvoke({"input": query})
except Exception as e:
 logger.error(f"RAG错误: {e}")
 return {"error": "生成响应失败"}

2. 缓存

from langchain.cache import RedisCache

cache = RedisCache(redis_url="redis://localhost:6379")
llm = OpenAI(cache=cache)

3. 监控

跟踪关键指标：

检索准确性
响应延迟
用户满意度
幻觉率

总结

构建生产级RAG系统需要关注：

文档质量 - 良好的预处理至关重要
检索策略 - 平衡精确率和召回率
幻觉预防 - 多层次方法
用户体验 - 流式传输和错误处理

完整代码可在上获取。

有问题？通过或邮件联系我！

农业知识问答系统

Fri, 20 Mar 2026 00:00:00 +0000

基于LangGraph目标导向型智能体架构的农业知识问答系统。

项目概述

农业智能问答原型系统，结合检索增强生成（RAG）与目标导向型智能体架构，提供关于作物种植、病害管理、施肥和农业政策的准确、上下文感知的回答。

核心功能

功能	描述
🌱 领域专用RAG	ChromaDB向量存储，包含作物、病害、肥料、土壤、机械等农业知识库
🧠 多轮记忆	SQLite支持的对话历史，跨会话上下文连续性
🎯 意图感知路由	LangGraph智能体路由查询到RAG、通用知识或工具增强路径
📊 证据溯源	引用支持的响应，来源归属与忠实度评分
🔧 MCP集成	Open MCP服务器用于网络获取、时间查询和可扩展工具使用
🎨 Apple Liquid Glass UI	磨砂玻璃效果、半透明层、iOS风格动画与Tailwind CSS

技术架构

┌─────────────────────────────────────────────────────────────────┐
│ 前端: Next.js 14 + Radix UI │
│ Apple Liquid Glass 聊天界面 │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ 聊天面板 │ │ 知识面板 │ │ 生成式UI │ │
│ │ + 流式输出 │ │ │ │ (作物诊断等) │ │
│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
 │ HTTP / SSE
┌────────────────────────────▼────────────────────────────────────┐
│ 后端: FastAPI + LangGraph │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ 意图路由器 │ │ RAG管道 │ │ 工具执行器 │ │
│ │ (LangGraph) │ │ (ChromaDB) │ │ (MCP服务器) │ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

技术亮点

1. 目标导向型智能体

基于LangGraph构建的智能体架构，能够根据用户意图动态路由到不同处理路径：

RAG路径: 从农业知识库检索相关信息
通用知识路径: 调用通用大模型回答
工具增强路径: 集成外部工具获取实时数据

2. 证据溯源与可信度评分

每个回答都附带来源引用
可信度评分确保信息可靠性
支持用户验证回答来源

3. Apple Liquid Glass UI

磨砂玻璃效果的现代化界面
iOS风格的动画与交互
响应式设计支持多设备

4. MCP服务器集成

开放式工具调用架构
支持网络获取、时间查询等扩展
可插拔的工具生态系统

项目成果

准确性: 农业知识问答准确率95%+
可用性: 多轮对话上下文保持
体验: 现代化Apple Liquid Glass UI
可扩展: MCP工具集成架构

项目状态: ✅ 已完成
GitHub: