杨劲松 - 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:

智颐养老护理系统

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

面向中型养老院的综合管理平台（B端运营后台 + C端家属小程序），覆盖健康评估、IoT设备监控、护理工单等核心业务。

🔒 项目仓库暂未公开。 以下为项目详情。

项目概述

面向中型养老院的综合管理平台，包含B端运营后台和C端家属小程序双端。覆盖健康评估、IoT设备监控、护理工单等核心业务。

团队6人协作开发，我负责 健康评估引擎、IoT同步服务 及 统一鉴权 三个模块，服务于院内500+设备、日均2000+次家属端访问。

技术架构

层级	技术选型
后端框架	Spring Boot 2.7 / MyBatis-Plus
数据库	MySQL 8.0 / Redis 7
IoT平台	华为云IoTDA
AI能力	百度千帆大模型
前端	Vue3 + Element Plus
安全	拦截器 + ThreadLocal

核心职责

1. 健康评估模块开发与性能优化

针对体检报告分析耗时痛点，集成 百度千帆AI大模型 进行语义分析
设计 Redis多级缓存 策略存储高频访问的健康建议
将单次分析响应时间从 8秒降低至1秒以内
护理人员查阅效率提升约 30%
有效支撑早高峰期间的高并发查询

2. IoT设备管理模块设计

开发 华为云IoT平台 对接服务
通过异步线程池实现产品列表与本地数据的 增量同步
设计"设备-位置"绑定逻辑确保数据一致性
列表同步耗时从 3分钟缩短至10秒
支持院内 500+设备 的实时状态监控

3. 安全认证体系构建

基于拦截器与 ThreadLocal 实现微信小程序用户的无感登录
实现多线程环境下的数据隔离与安全
零内存泄漏稳定运行
支撑小程序端日均 2000+次 活跃访问

项目成果

性能: AI分析响应时间从8s降至1s以内
同步: IoT设备列表同步从3min降至10s
规模: 支持500+设备实时监控、日均2000+次访问
稳定: 零内存泄漏，稳定支撑生产环境

项目状态: ✅ 已完成
仓库状态: 🔒 暂未公开，敬请期待

conda 学习路线

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

docker 学习路线

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

elasticsearch 学习路线

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

FastAPI AI Streaming API：用 SSE 交付增量结果

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

上图：FastAPI — FastAPI AI Streaming API。

流式响应改善的是首字节延迟和用户感知，不是让模型计算更快。接口需要明确事件格式、结束信号、异常事件和客户端断开后的清理动作。

核心心智模型

服务器以 data 事件发送，客户端按事件边界解析。不要把任意未转义文本拼成 SSE；更推荐 JSON 事件并统一 type 字段。

关键机制

生成器用 try/finally 释放上游资源；每个事件携带 request id；模型错误转换成 error 事件并明确关闭。

Python 示例

import json
from fastapi.responses import StreamingResponse

async def events(prompt: str):
 try:
 async for token in provider.stream(prompt):
 yield f"data: {json.dumps({'type': 'token', 'text': token})}\n\n"
 yield "data: {\"type\":\"done\"}\n\n"
 except Exception:
 yield "data: {\"type\":\"error\",\"code\":\"upstream_failed\"}\n\n"

@app.post("/v1/chat/stream")
async def stream(req: ChatRequest):
 return StreamingResponse(events(req.message), media_type="text/event-stream")

课程定位

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

工程实践

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

常见错误

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

生产检查清单

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

练习建议

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

动手练习

写一个浏览器端 SSE 客户端，分别测试正常完成、上游报错、用户刷新页面和网络断开。记录 TTFT、完整响应耗时以及未完成流的取消率。

总结

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

FastAPI Async 与依赖注入：避免阻塞事件循环

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

上图：FastAPI — FastAPI Async 与依赖注入。

async def 并不会自动让阻塞代码变快。文件 I/O、同步 SDK、CPU 密集任务如果直接运行在事件循环中，会拖慢所有请求。

核心心智模型

异步路由适合等待异步网络 I/O；同步依赖应明确隔离，CPU 任务放入任务队列或进程池。依赖注入的重点是生命周期可见、替换容易。

关键机制

在 lifespan 创建共享客户端，在请求结束后复用连接；用 semaphore 限制并发外部调用，避免本地服务把供应商打爆。

Python 示例

import asyncio
from contextlib import asynccontextmanager
from fastapi import FastAPI

limit = asyncio.Semaphore(20)

async def call_provider(client, payload):
 async with limit:
 return await client.post("/responses", json=payload, timeout=15)

@asynccontextmanager
async def lifespan(app: FastAPI):
 app.state.client = make_async_client()
 yield
 await app.state.client.aclose()

app = FastAPI(lifespan=lifespan)

课程定位

工程实践

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

常见错误

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

生产检查清单

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

练习建议

动手练习

用一个同步假客户端和一个异步假客户端压测 50 个并发请求，比较事件循环阻塞情况；再加入 semaphore，观察上游错误率与平均延迟。

总结

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

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)

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 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 变成可维护的系统。

fastapi 学习路线

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

git 学习路线

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

Java 并发模型：线程池、锁与可见性

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

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

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

这张图围绕“A notification service absorbs bursts with a bounded pool and a visible rejection policy.”展开。学习 Java Concurrency Model 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Shared state → synchronization → safe result。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Core Pool Size + Maximum Pool Size；Work Queue → backpressure boundary。这些机制决定延迟、吞吐和可测试性。
资源与状态：Keep Alive Time → idle worker policy；Rejected Handler → explicit overload path。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：CAS: expected → compare → swap；必要时再结合 volatile / lock → memory visibility 做降级、重试或回滚。

一个可落地的最小实现

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

var pool = new ThreadPoolExecutor(8, 32, 30,
 TimeUnit.SECONDS, new ArrayBlockingQueue<>(500),
 new ThreadPoolExecutor.CallerRunsPolicy());

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

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

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

Java 核心架构：从源码到 JVM 执行

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

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

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

这张图围绕“A payment service starts slowly, then becomes faster as JIT compiles its hot methods.”展开。学习 Java Core Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

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

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Class Loader → load / link / initialize；Heap → objects + GC managed memory。这些机制决定延迟、吞吐和可测试性。
资源与状态：Stack → frames + local variables；Method Area → class metadata。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：PC Register + Native Method Stack；必要时再结合 Execution Engine → Interpreter + JIT 做降级、重试或回滚。

一个可落地的最小实现

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

public final class OrderService {
 public Order create(CreateOrder cmd) {
 return repository.save(validator.check(cmd));
 }
}

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

Java 集合与 HashMap：从 key 到 bucket

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

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

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

这张图围绕“An order API deduplicates request IDs before writing to MySQL.”展开。学习 Java Collections & HashMap Internals 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Collection hierarchy + hash spreading + collision handling。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：key → hash() → hash spreading；index = (n - 1) & hash。这些机制决定延迟、吞吐和可测试性。
资源与状态：Bucket: Node → Node → Node；Collision → Linked List / Tree Bin。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Capacity × Load Factor → Resize；必要时再结合 Average lookup O(1) when distribution is healthy 做降级、重试或回滚。

一个可落地的最小实现

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

Map<String, Long> seen = new HashMap<>(1024);
seen.putIfAbsent(requestId, System.nanoTime());

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

java 学习路线

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

jupyter 学习路线

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

JVM 内存与 GC：对象从 Eden 到回收

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

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

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

这张图围绕“A recommendation API protects p99 latency by measuring allocation bursts rather than guessing GC flags.”展开。学习 JVM Memory & Garbage Collection 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Allocation → promotion → reachability → collection。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：GC Root → Reachability Analysis；Young Gen: Eden + Survivor From / To。这些机制决定延迟、吞吐和可测试性。
资源与状态：Minor GC → copy live objects；Promotion → long-lived objects enter Old Gen。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Mark → Sweep / Compact；必要时再结合 G1 / ZGC → choose for latency goals 做降级、重试或回滚。

一个可落地的最小实现

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

GC Root → reachable objects → mark → reclaim / compact
Eden → Survivor → Old Generation

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

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))

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 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 变成可维护的系统。

langchain 学习路线

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

linux 学习路线

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

MySQL 内部架构：SQL 层到 InnoDB

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

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

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

这张图围绕“A read API uses a pool and EXPLAIN to ensure its query reaches an index instead of scanning the table.”展开。学习 MySQL Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Connection → Parser → Optimizer → Executor → Storage Engine。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Connection Layer → sessions + auth；SQL Layer → parse / optimize / execute。这些机制决定延迟、吞吐和可测试性。
资源与状态：Cost model chooses access path；InnoDB → Buffer Pool + B+Tree。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Redo Log → crash recovery durability；必要时再结合 Undo Log → rollback + consistent reads 做降级、重试或回滚。

一个可落地的最小实现

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

EXPLAIN SELECT id, name FROM user
WHERE tenant_id = 7 AND status = 'active';

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

MySQL 事务与 MVCC：一致性读如何成立

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

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

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

这张图围绕“Inventory deduction uses a short transaction and row locking; a deadlock retry is idempotent.”展开。学习 MySQL Transaction & MVCC 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：BEGIN → SQL → Undo Log / Read View → COMMIT。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Atomicity → all or rollback；Consistency → constraints + invariants。这些机制决定延迟、吞吐和可测试性。
资源与状态：Isolation → visibility policy；Durability → redo log + flush。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Undo Log → older row versions；必要时再结合 Read View → choose visible snapshot 做降级、重试或回滚。

一个可落地的最小实现

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

START TRANSACTION;
SELECT stock FROM inventory WHERE sku = ? FOR UPDATE;
UPDATE inventory SET stock = stock - 1 WHERE sku = ?;
COMMIT;

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

MySQL 索引与 B+Tree：让查询走 Fast Path

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

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

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

这张图围绕“A user-search endpoint compares its EXPLAIN plan before and after adding a composite index.”展开。学习 MySQL Index & B+Tree 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：SQL → Index → B+Tree search → Leaf → Row。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Root → Internal Node → Leaf Node；Leaf: key → primary key / row pointer。这些机制决定延迟、吞吐和可测试性。
资源与状态：Clustered Index → primary key + data；Secondary Index → key + primary key。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Range scan keeps ordered leaf traversal；必要时再结合 Full Table Scan × when selectivity is poor 做降级、重试或回滚。

一个可落地的最小实现

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

CREATE INDEX idx_user_status_created
ON user(status, created_at);

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

mysql 学习路线

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

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 变成可维护的系统。

openai 学习路线

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

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)

场景中的工程决策

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

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 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 运行时：源码、字节码与对象模型

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 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

redis 学习路线

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

rocketmq 学习路线

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

Spring Boot IoC 与依赖注入：让对象可替换

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

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

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

这张图围绕“The same payment use case runs with a sandbox gateway in tests and a real gateway in production.”展开。学习 Spring Boot IoC & Dependency Injection 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Container owns construction; application owns behavior。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Scan / Register → BeanDefinition；Instantiate → constructor injection。这些机制决定延迟、吞吐和可测试性。
资源与状态：Populate → dependencies are resolved；Initialize → @PostConstruct / proxy。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Ready → request can use the Bean；必要时再结合 Destroy → cleanup resources 做降级、重试或回滚。

一个可落地的最小实现

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

@Service
class PaymentService {
 PaymentService(PaymentGateway gateway) { ... }
}

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

Spring Boot 请求生命周期：从 HTTP 到响应

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

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

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

这张图围绕“A public API distinguishes authentication errors, validation errors, and downstream timeouts.”展开。学习 Spring Boot Request Lifecycle 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Filter → DispatcherServlet → Controller → Response。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Filter → trace id / auth / CORS；Handler Mapping → select endpoint。这些机制决定延迟、吞吐和可测试性。
资源与状态：Argument Resolver → bind + validate DTO；Interceptor → timing / policy checks。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Exception Handler → stable error schema；必要时再结合 Message Converter → JSON response 做降级、重试或回滚。

一个可落地的最小实现

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

Filter → HandlerMapping → Controller → Service
 → ExceptionHandler / MessageConverter

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

Spring Boot 应用架构：Controller 到 Database

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

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

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

这张图围绕“An order endpoint keeps HTTP, business rules, and SQL separate so each layer can be tested independently.”展开。学习 Spring Boot Application Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Client → Controller → Service → Repository → Database。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：BeanDefinition → BeanFactory → ApplicationContext；@Controller → transport boundary。这些机制决定延迟、吞吐和可测试性。
资源与状态：@Service → domain orchestration；@Repository → persistence boundary。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Auto Configuration + Starter；必要时再结合 Embedded Server + externalized config 做降级、重试或回滚。

一个可落地的最小实现

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

@RestController
class OrderController {
 private final OrderService service;
 OrderController(OrderService service) { this.service = service; }
}

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

spring-boot 学习路线

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

生产级 MySQL 高并发架构：缓存、读写分离与分片

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

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

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

这张图围绕“A feed service handles a hot tenant by caching reads, routing writes to the master, and testing restore before launch.”展开。学习 Production MySQL High-Concurrency Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Client → Pool → Cache / Master / Replicas → Backup。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Cache-aside → read cache, write source；Master → writes + binlog。这些机制决定延迟、吞吐和可测试性。
资源与状态：Replicas → read scaling with lag awareness；Sharding → user_0 … user_N。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：Slow Query → EXPLAIN → index tuning；必要时再结合 Backup → restore drill, not just backup files 做降级、重试或回滚。

一个可落地的最小实现

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

read: Redis → Replica → Master fallback
write: idempotency → Master → binlog / event

场景中的工程决策

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

先保护依赖：连接池、线程池、并发信号量或缓存都要有上限，不能用无限队列掩盖下游过载。
再保证正确性：幂等键、事务边界、版本号、锁或 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 架构。

从 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 变成可维护的系统。

生产级 Spring Boot 架构：可观测的服务边界

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

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

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

这张图围绕“A flash-sale service protects the database with cache, bounded writes, idempotency, and asynchronous inventory events.”展开。学习 Production Spring Boot Architecture 时，不能只记住组件名称：要能说明输入从哪里来、状态由谁持有、哪个组件承担失败、以及如何用指标证明系统仍然健康。白板中的箭头对应代码边界，红色感叹号对应需要显式处理的风险。

逐层拆解

主流程是：Gateway → Service → Cache / DB / MQ → Observability。前半段是请求或数据的进入路径，后半段是运行时、存储或执行结果。

边界契约：先确定输入、输出和错误结构；不要让隐式类型、未校验参数或共享可变状态穿透多层。
核心机制：Nginx / Gateway → auth + rate limit；Service → idempotency + transaction。这些机制决定延迟、吞吐和可测试性。
资源与状态：Redis → cache-aside with TTL；MySQL → source of truth。生产系统必须说明资源何时创建、何时释放，以及状态是否可恢复。
失败路径：RocketMQ → async side effects；必要时再结合 Metrics + Logs + Traces → feedback loop 做降级、重试或回滚。

一个可落地的最小实现

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

request → idempotency → transaction → outbox event
 → Redis / MySQL / MQ → trace + metrics

场景中的工程决策

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

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

常见误区

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

生产检查清单

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

总结

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, 15 May 2026 00:00:00 +0000

微服务电商平台 - SpringCloud Alibaba技术栈 + MyBatis-Plus + Feign远程调用。

项目概述

从单体架构到微服务演进的完整实践，覆盖企业级中间件集成与分布式解决方案。项目对标中高级Java后端工程师核心能力模型，按技术深度分层实现。

专业GOAL（岗位能力对标）

层级	能力域	覆盖模块	权重
🥇 分布式架构	微服务拆分、服务治理、分布式事务、消息队列	mall-order-service, mall-seckill-service, Middleware	35%
🥈 中间件深度	Redis缓存、ES搜索、RocketMQ消息、Seata事务、Sentinel限流	docs/Middleware/ (11个中间件)	30%
🥉 业务实现	商品/用户/购物车/订单CRUD、JWT鉴权、AOP日志	mall-product-service, mall-user-service, mall-cart-service	25%
🏅 工程化	Docker容器化、Gateway网关、Nacos配置中心、CI部署	mall-gateway, docs/docker/	10%

核心职责

主导秒杀链路、搜索/RAG、分布式一致性与研发规范。

技术架构

┌──────────┐ ┌──────────┐ ┌──────────┐
│ 客户端 │ │ 客户端 │ │ 客户端 │
└────┬─────┘ └────┬─────┘ └────┬─────┘
 └──────────────┴──────────────┘
 │
 ┌──────┴──────┐
 │ Spring Cloud │
 │ Gateway │ ← 统一鉴权 + 路由 + 限流
 └──────┬──────┘
 │
 ┌──────────┼──────────┐
 │ │ │
┌────┴────┐ ┌──┴───┐ ┌───┴────┐
│ 业务服务 │ │ 中间件 │ │ 基础设施 │
│ User │ │ Redis │ │ Nacos │
│ Product │ │ MySQL │ │ Sentinel│
│ Order │ │ Mongo │ │ Seata │
│ Cart │ │ ES │ │ XXL-Job │
│ Pay │ │ MQ │ │ │
│ Seckill │ │ Canal │ │ │
└─────────┘ └──────┘ └─────────┘

项目结构

mall-micro-cloud/
├── mall-api/ # Feign接口声明层
├── mall-common/ # 公共工具模块
├── mall-gateway/ # Spring Cloud Gateway网关
├── mall-services/
│ ├── mall-user-service/ # 用户服务（JWT + BCrypt鉴权）
│ ├── mall-product-service/ # 商品服务（MyBatis-Plus）
│ ├── mall-cart-service/ # 购物车服务（Redis缓存）
│ ├── mall-order-service/ # 订单服务（Seata分布式事务）
│ ├── mall-pay-service/ # 支付服务（RocketMQ事务消息）
│ ├── mall-seckill-service/ # 秒杀服务（高并发 + 限流）
│ ├── mall-es-service/ # 商品搜索服务（Elasticsearch）
│ ├── mall-oss-service/ # 对象存储服务
│ ├── mall-scheduler-service/ # 分布式调度服务（XXL-Job）
│ ├── mall-consumer-service/ # 消息消费服务
│ └── mall-test-service/ # 测试服务
├── docs/
│ ├── Middleware/ # 11个中间件实战文档
│ ├── interview/ # 面试题库（9章）
│ ├── db-sql/ # 业务表SQL
│ └── docker/ # Docker容器化部署指南
└── pom.xml # Maven父POM

技术亮点

1. 分布式架构

微服务拆分: 按业务域拆分为用户、商品、订单、支付等独立服务
服务治理: Nacos服务注册发现 + Gateway统一路由
分布式事务: Seata AT模式保证跨服务数据一致性

2. 中间件深度集成

Redis: 缓存 + 分布式锁 + 会话管理
Elasticsearch: 全文搜索 + IK分词
RocketMQ: 异步消息 + 事务消息
Sentinel: 限流降级 + 熔断保护

3. 高并发秒杀

Redis预扣库存 + Redisson可重入锁
RocketMQ异步落库解决超卖
Sentinel限流保护系统稳定

4. 工程化实践

Docker容器化部署
Gateway统一鉴权
Nacos配置中心

项目成果

架构: 完成11个微服务拆分与治理
中间件: 集成11个企业级中间件
性能: 万级并发压测稳定运行
文档: 完整的中间件实战文档与面试题库

项目状态: ✅ 已完成
GitHub:

农业知识问答系统

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:

专业能力矩阵

Mon, 05 Jan 2026 00:00:00 +0000

专业能力矩阵

🎯 岗位目标：Java后端 / AI应用开发工程师

核心能力对标

能力层级	核心能力	项目实践	掌握程度
P0 核心	Java微服务架构	分布式微云商城	⭐⭐⭐⭐⭐
P0 核心	AI应用开发（RAG/Agent）	Agri-QA-Assistant	⭐⭐⭐⭐⭐
P1 重要	数据库设计与优化	MySQL + Elasticsearch	⭐⭐⭐⭐
P1 重要	分布式系统设计	Seata + RocketMQ	⭐⭐⭐⭐
P2 加分	前端开发	Next.js + React	⭐⭐⭐
P2 加分	DevOps与部署	Docker + Nacos	⭐⭐⭐⭐

🏗️ 技术能力图谱

1. Java微服务技术栈

Spring Boot 3.3.2
 ↓
Spring Cloud Alibaba
 ↓
┌─────────────────────────────────────┐
│ Nacos (服务发现/配置中心) │
│ Gateway (统一网关/鉴权/限流) │
│ Sentinel (熔断/降级/限流) │
│ Seata (分布式事务) │
│ OpenFeign (远程调用) │
└─────────────────────────────────────┘
 ↓
MyBatis-Plus (ORM)
 ↓
MySQL + Redis + Elasticsearch

2. AI应用开发技术栈

Python 3.10+
 ↓
┌─────────────────────────────────────┐
│ LangChain (智能体编排) │
│ LangGraph (目标导向型路由) │
│ FastAPI (异步Web框架) │
│ ChromaDB (向量存储) │
└─────────────────────────────────────┘
 ↓
RAG Pipeline
 ↓
┌─────────────────────────────────────┤
│ 文档预处理 → 向量化 → 检索 → 生成 │
│ 多轮记忆 → 证据溯源 → 幻觉控制 │
└─────────────────────────────────────┘

📊 项目与能力映射

分布式微云商城

能力域	具体实现	成果指标
微服务拆分	11个独立服务	按业务域解耦
服务治理	Nacos + Gateway	统一路由鉴权
分布式事务	Seata AT模式	跨服务数据一致
高并发	Redis + RocketMQ	万级QPS稳定
搜索	ES + IK分词	2s→20ms响应

Agri-QA-Assistant

能力域	具体实现	成果指标
智能体架构	LangGraph路由	意图识别准确率95%
RAG管道	ChromaDB + 文档分块	检索召回率90%+
多轮记忆	SQLite会话管理	上下文保持完整
证据溯源	来源引用 + 可信度评分	幻觉率<5%
UI设计	Apple Liquid Glass	现代化交互体验

🚀 职业发展路径

短期目标（0-1年）

✅ 完成Java微服务项目
✅ 完成AI应用开发项目
🎯 进入Java后端/AI应用开发岗位

中期目标（1-3年）

深入分布式系统设计
掌握云原生架构
成为技术骨干

长期目标（3-5年）

架构师/技术专家
技术团队管理
行业解决方案

💼 求职优势

1. 技术深度

Java微服务全栈能力
AI应用开发实战经验
分布式系统设计能力

2. 项目质量

企业级项目架构
完整技术文档
可量化成果指标

3. 学习能力

快速掌握新技术
主动解决技术难题
持续输出技术文章

📞 联系方式

GitHub:
邮箱:
求职意向: Java后端 / AI应用开发工程师
到岗时间: 2026年9月可实习，2027年6月全职

专业能力矩阵已建立，欢迎交流合作！ 🎉

🧭 16 技术栈专业 Goal 总览

总 Goal： 在 2026 年内完成一条“Java 后端 + AI 应用 + 分布式工程”的可验收能力链：每项技术都要做到 能解释架构、能写最小实现、能处理故障、能用项目验收，而不是只停留在 API 记忆。

主页的 16 张技术栈卡片已经接入学习详情页：。每个详情页都包含配套架构图、教程入口、学习速览、路线大纲、练习与完成定义。

学习优先级与顺序

阶段	技术栈	阶段性 Goal	验收标准
P0 核心路线	、、、、、	打通后端服务与 AI 应用闭环	完成一个带测试、日志、错误处理、证据引用的 AI 服务，并能解释关键架构取舍
P1 工程深化	、、、、	把 Demo 提升为可承压、可检索、最终一致的工程系统	用执行计划、压测、消息重放和故障演练证明性能、一致性与可恢复性
P2 交付工具	、、、、	让开发、实验、部署和协作可复现	新环境一条命令启动；提交可审计；服务可监控；实验可重跑

16 项完成定义

Java / Spring Boot： 能从领域建模到 REST 服务、测试与健康检查，说明并发、事务和配置边界。
Python / FastAPI： 能实现类型安全的异步 API，处理取消、超时、上游失败与流式断连。
LangChain / OpenAI： 能用结构化输出和工具调用构建可替换、可评测的模型链路，并控制密钥、成本和重试。
RAG / Elasticsearch： 能完成索引、召回、重排、引用与拒答，拥有 Recall@K、命中率、延迟等基线。
MySQL / Redis： 能解释索引、MVCC、锁、缓存一致性和热点保护，并通过并发测试验证。
RocketMQ： 能实现幂等消费、重试、死信、积压告警与业务补偿，支持安全重放。
Docker / Linux： 能以最小权限和健康检查部署服务，使用进程、网络、日志、资源四层定位故障。
Git / Conda / Jupyter： 能让代码、依赖和实验可审计、可复现、可交接。

阶段性验收节奏

每周： 选一个技术栈详情页，读懂配套图，完成一个最小 Demo，并记录一个失败案例。
每两周： 将两个以上技术栈连成可运行链路，例如 Spring Boot + MySQL + Redis，或 FastAPI + RAG + OpenAI。
每月： 进行一次故障演练和复盘：超时、限流、空结果、重复消息、缓存失效、容器重启至少覆盖一项。
阶段完成： 输出代码、README、架构图、测试报告和指标对比；只有满足“能解释、能实现、能验证、能恢复”才标记完成。