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

灵犀智能写作

Mon, 24 Aug 2026 00:00:00 +0000

基于 Spring Boot 3 + Spring AI Alibaba 构建的 AI 智能图文创作平台，独立全栈设计与开发。

项目概述

灵犀写作是一个基于 Spring Boot 3 + Spring AI Alibaba 构建的 AI 智能图文创作平台。作为独立全栈设计与开发的个人项目，旨在探索大模型在长文生成领域的落地应用。

系统创新性地引入 StateGraph 工作流引擎 编排多智能体协作，结合 SSE 流式输出 技术，解决了传统 AI 生成等待时间长、内容结构松散的问题。作为一个高并发、可扩展的后端架构实践，该系统完整实现了从灵感激发到配图生成的自动化闭环。

核心功能

功能	描述
🧠 多智能体编排	StateGraph工作流引擎，标题生成、大纲构建、正文撰写多智能体灵活编排
⚡ 流式输出	SSE技术毫秒级首字上屏，消除等待焦虑
🔄 异步任务体系	ThreadPoolTaskExecutor + @Async，长耗时操作解耦为后台任务
🖼️ 多源配图	策略模式动态接入Pexels/SVG等多源配图服务，自动降级切换
📐 结构化输出	Prompt模板引擎 + StructuredOutputConverter，统一不同大模型的输出格式
📊 任务追踪	任务状态tracking机制，进度管理与结果回调

技术架构

┌─────────────────────────────────────────────────────────────┐
│ 前端 (Vue 3) │
│ 流式渲染 + 任务进度 + 图文编辑 │
└──────────────────────────┬──────────────────────────────────┘
 │ SSE (Server-Sent Events)
┌──────────────────────────▼──────────────────────────────────┐
│ Spring Boot 3 + Spring AI Alibaba 后端 │
│ ┌────────────────┐ ┌────────────────┐ ┌───────────────┐ │
│ │ StateGraph │ │ ThreadPoolTask │ │ Prompt模板 │ │
│ │ 工作流引擎 │ │ Executor异步 │ │ 引擎+策略模式 │ │
│ │ (多智能体编排) │ │ 任务体系 │ │ (多源配图) │ │
│ └────────────────┘ └────────────────┘ └───────────────┘ │
└──────────┬──────────────────┬──────────────────┬─────────────┘
 │ │ │
 ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ Spring AI │ │ Redis │ │ MyBatis │
 │ Alibaba │ │ (缓存/状态)│ │ Flex(DB) │
 └───────────┘ └───────────┘ └───────────┘

技术亮点

1. 多智能体编排架构

摒弃传统的线性调用，基于 StateGraph 自主设计工作流引擎：

标题生成、大纲构建、正文撰写等多智能体灵活编排
串行/并行组合，复杂长文生成任务拆解为可维护节点流程
新增一种生成模式仅需配置新节点即可，系统可扩展性显著提升

2. 高并发流式响应

针对大模型生成慢的痛点：

SSE (Server-Sent Events) 技术整合前端对接
ThreadPoolTaskExecutor 构建异步任务体系
毫秒级首字上屏，接口吞吐量提升 50%

3. 高容错图文生成链路

Prompt 模板引擎与 StructuredOutputConverter 统一输出格式
策略模式动态接入 Pexels/SVG 等多源配图服务
单一图源失败时自动降级切换，保证 99% 以上生成成功率

4. 异步任务与状态追踪

@Async 将文章生成、图片生成等耗时操作解耦为后台任务
任务状态 tracking 机制，进度管理与结果回调
显著提升系统吞吐能力，避免接口阻塞

项目成果

架构: StateGraph工作流引擎 + 多智能体编排
性能: 毫秒级首字上屏，接口吞吐量提升 50%
可靠性: 多源配图自动降级，生成成功率 99%+
可扩展: 新增生成模式仅需配置新节点

项目状态: ✅ 已完成
GitHub:

LangChain Memory：设计可控的多轮对话状态

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

上图：LangChain — LangChain Memory。

多轮对话的难点不是把所有消息都塞回 prompt，而是决定哪些事实需要保留、保留多久、由谁负责删除。记忆应被视为显式数据，而不是模型的隐性能力。

核心心智模型

短期记忆服务当前会话，摘要记忆压缩较早内容，长期记忆保存经用户同意的偏好。三者都应带 conversation_id、租户隔离和过期策略。

关键机制

先计算 token 预算，再决定截断或摘要；写入长期记忆前做 PII 过滤和去重。读取记忆时标注来源和时间，避免旧事实覆盖新事实。

Python 示例

from dataclasses import dataclass
from datetime import datetime

@dataclass
class MemoryItem:
 conversation_id: str
 text: str
 source: str
 created_at: datetime

def build_context(history: list[MemoryItem], max_chars: int = 6000) -> str:
 selected, size = [], 0
 for item in reversed(history):
 if size + len(item.text) > max_chars: break
 selected.append(f"[{item.source}] {item.text}")
 size += len(item.text)
 return "\n".join(reversed(selected))

课程定位

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

工程实践

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

常见错误

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

生产检查清单

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

练习建议

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

动手练习

实现最近消息、会话摘要、用户偏好三级上下文，并记录每次摘要覆盖了哪些消息 id。删除会话时，验证缓存、向量库和审计副本是否都被清理。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，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 Tool Calling Agent：把决策与执行分开

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

上图：LangChain — LangChain Tool Calling Agent。

Agent 并不是让模型直接操作系统，而是让模型提出结构化的工具意图，由应用程序校验并执行。最重要的边界是：模型决定，应用执行。

核心心智模型

循环由 Think → Call → Observe 组成，但循环次数、工具白名单、参数校验和权限都由宿主应用控制。工具描述越清晰，模型越容易选对；描述不是安全策略的替代品。

关键机制

工具返回可机器读取的成功或失败结果；不要把异常堆栈直接暴露给模型或用户。对写操作要求显式确认，并为每次调用记录审计事件。

Python 示例

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> dict:
 """Return current weather for an allowed city."""
 if city not in {"Shanghai", "Beijing"}:
 return {"ok": False, "error": "city_not_allowed"}
 return {"ok": True, "city": city, "celsius": 26}

llm_with_tools = model.bind_tools([get_weather])
message = llm_with_tools.invoke("上海今天适合跑步吗？")
if message.tool_calls:
 result = get_weather.invoke(message.tool_calls[0]["args"])

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

增加一个只读搜索工具和一个有副作用的退款工具。让前者自动执行，让后者返回 requires_confirmation，并测试模型无法绕过确认步骤。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，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 变成可维护的系统。

OpenAI Multimodal AI：统一处理文本、图片与文档

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

上图：OpenAI — OpenAI Multimodal AI。

多模态应用的难点在输入治理，而不是把文件上传给模型。每种媒体都需要类型校验、大小限制、内容安全、权限控制和可追溯的预处理。

核心心智模型

Input → Normalize → Multimodal Model → Structured Output → Application。图片可能需要降采样，PDF 可能需要 OCR/版面解析，音频需要转写与时间戳。

关键机制

把文件存储和模型请求解耦：先生成短期对象地址并做病毒扫描，再按最小分辨率/页数发送。响应保存 modality、处理版本和证据区域。

Python 示例

from pydantic import BaseModel, Field

class ImageInsight(BaseModel):
 objects: list[str] = Field(default_factory=list, max_length=20)
 summary: str = Field(max_length=1000)
 confidence: float = Field(ge=0, le=1)

def validate_upload(content_type: str, size: int) -> None:
 if content_type not in {"image/png", "image/jpeg", "application/pdf"}:
 raise ValueError("unsupported_media_type")
 if size > 10 * 1024 * 1024:
 raise ValueError("file_too_large")

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

做一个发票图片 → 结构化字段的小实验，分别提交清晰图片、旋转图片、低分辨率图片和超大 PDF，记录字段准确率、处理时延和成本。

总结

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

OpenAI Structured Output：让模型输出可验证的数据

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

上图：OpenAI — OpenAI Structured Output。

自由文本适合展示，结构化输出适合驱动程序。Structured Output 的目标不是让模型永不出错，而是让成功、拒答和失败都能被程序区分。

核心心智模型

schema 约束字段类型、必填项和枚举，但不能保证事实正确。业务层还要检查金额范围、实体权限、引用存在性等语义规则。

关键机制

将解析分成 transport、schema、domain 三层；遇到 refusal 或不完整结果时不要强行填默认值，否则会把不确定性伪装成事实。

Python 示例

from pydantic import BaseModel, Field

class Incident(BaseModel):
 severity: str = Field(pattern="^(low|medium|high)$")
 summary: str = Field(min_length=1, max_length=500)
 actions: list[str] = Field(min_length=1, max_length=5)

response = client.responses.parse(model="gpt-4o-mini", input="整理故障记录", text_format=Incident)
if response.output_parsed is None: raise ValueError("model_refusal_or_parse_failure")

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

给 schema 增加版本号与向后兼容字段，准备正常、拒答、缺字段和越界四种 fixture，验证 API 不会返回看似成功的半结构化 JSON。

总结

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

OpenAI Tool Calling：函数声明、执行循环与安全边界

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

上图：OpenAI — OpenAI Tool Calling。

Tool Calling 让模型输出函数名和参数，而不是直接执行函数。应用必须验证函数是否允许、参数是否合规、调用者是否有权限，然后把结果以工具消息回传。

核心心智模型

循环是 request → tool_call → validate → execute → tool_result → request。每一轮都有最大次数，最终答复不能绕过业务授权。

关键机制

schema 描述怎样调用，策略层决定是否允许调用。读操作可以自动执行，写操作应二次确认、幂等并审计。

Python 示例

def execute_tool(call, user):
 if call.name not in TOOL_ALLOWLIST:
 return {"ok": False, "error": "tool_not_allowed"}
 args = validate_args(call.name, call.arguments)
 authorize(user, call.name, args)
 if is_side_effecting(call.name) and not user.confirmed:
 return {"ok": False, "error": "confirmation_required"}
 return TOOL_REGISTRY[call.name](**args)

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

实现天气查询和退款申请两个工具；让模型可以自动查天气，但退款必须经过用户确认、幂等键和审计日志。

总结

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

RAG Embedding 与向量数据库：相似度背后的工程细节

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

上图：RAG — RAG Embedding 与向量数据库。

向量数据库并不会自动理解业务语义；它只负责在给定向量空间里高效找近邻。真正的工程问题是 embedding 版本、距离度量、过滤条件与数据一致性。

核心心智模型

文档和 query 必须使用兼容的 embedding 模型与预处理。索引记录应包含 embedding_model、dimensions、corpus_version，便于重建和回滚。

关键机制

先做 metadata filter 再做向量搜索，避免把不同租户、语言和权限的数据混在候选集里。

Python 示例

from uuid import uuid4

record = {
 "id": str(uuid4()),
 "text": "退款申请需要订单号和原因。",
 "vector": embed("退款申请需要订单号和原因。"),
 "metadata": {"tenant_id": "acme", "language": "zh", "embedding_model": "text-embedding-3-small", "corpus_version": "2026-08-21"},
}
# 相似度不是权限判断

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

用同一批文档分别建立两个 embedding 版本，记录维度、索引大小、Top-K 重叠率和评测集 Recall@K，再决定是否切换。

总结

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

RAG Retriever 优化：从 Top-K 到混合检索与重排

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

上图：RAG — RAG Retriever 优化。

检索优化的目标不是召回越多越好，而是在有限上下文和延迟预算内，把真正支持答案的证据排在前面。

核心心智模型

关键词检索擅长精确术语，向量检索擅长语义表达；混合召回取两者候选，再用 reranker 结合 query 与文档重排。

关键机制

用离线评测集调整 chunk size、overlap、K、阈值和 reranker。单独提高 Recall 可能增加噪声，最终要看 nDCG、答案支持率和端到端延迟。

Python 示例

def hybrid_retrieve(query: str, k: int = 20):
 dense = vector_store.search(query, k=k)
 lexical = bm25.search(query, k=k)
 candidates = deduplicate(dense + lexical)
 ranked = reranker.rank(query, candidates)
 return [item for item in ranked if item.score >= 0.35][:5]

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

准备包含缩写、数字和同义改写的查询集，比较纯向量、纯 BM25、混合召回和重排四个版本，画出 Recall@K 与延迟曲线。

总结

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

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 架构：权限、版本与可观测性

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

上图：RAG — 生产级 RAG 架构。

从 demo 到生产的差距主要在边界条件：谁能看到文档、索引如何更新、答案如何引用、上游不可用时怎么办。

核心心智模型

把系统分成 ingestion、indexing、query serving 和 evaluation 四个平面；在线请求只读当前 active index，更新在后台构建并原子切换。

关键机制

权限过滤必须在检索阶段执行；缓存键包含 tenant、权限摘要、query 规范化版本和 index version；删除文档要能传播到所有副本。

Python 示例

from dataclasses import dataclass

@dataclass
class QueryContext:
 tenant_id: str
 allowed_collections: set[str]
 index_version: str

def cache_key(query: str, ctx: QueryContext) -> str:
 scopes = ",".join(sorted(ctx.allowed_collections))
 return f"rag:v2:{ctx.tenant_id}:{ctx.index_version}:{scopes}:{normalize(query)}"

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

设计 active/candidate 两套索引，模拟一次失败发布和一次文档删除，检查流量是否仍读到旧权限数据，并为每次回答保存 evidence ids。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，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: