Python on 方糖猫Blog

Spring Boot + Python 双栈架构：AI 服务的工程化实践

Mon, 20 Apr 2026 14:00:00 +0800

Spring Boot + Python 双栈架构：AI 服务的工程化实践

我开发的方糖猫 AI 视频平台不是一个纯 Python 项目，也不是一个纯 Java 项目。它同时使用了 Spring Boot 3 和 Python 3.11：Java 负责业务系统和 API 服务，Python 负责 AI 推理、渲染和多媒体处理。这篇文章会分享我们为什么要这样做，以及如何解决两个技术栈之间的协作问题。

一、为什么必须双栈？

做一个 AI 视频生成平台，需要两类能力：

能力类型	典型需求	更适合的栈
企业级业务系统	用户、订单、权限、支付、任务管理	Java / Spring Boot
AI 推理与多媒体	LLM 调用、Whisper、RAG、Remotion、FFmpeg	Python

Java 的优势在于生态成熟、工程规范、团队熟悉；Python 的优势在于 AI 库丰富、模型推理和多媒体处理工具链完善。

如果全用 Java，AI 库支持差，很多模型没有 Java SDK；如果全用 Python，业务系统的稳定性、事务处理、监控运维又很难做好。

所以我们的选择是：Java 做业务底盘，Python 做 AI 引擎，两者通过清晰的接口协作。

二、整体架构

flowchart TD
    FE["前端 (Vue 3)"]
    GW["API 网关 / BFF (Spring Boot)<br/>用户认证、请求路由、限流、任务状态查询、SSE 推送"]
    BIZ["业务服务<br/>(Spring Boot)"]
    SCHED["任务调度服务<br/>(Spring Boot)"]
    RES["资源管理服务<br/>(Spring Boot)"]
    AI["AI Worker (Python)<br/>ReAct Agent、RAG 检索、Whisper、TTS、Remotion、FFmpeg"]
    STORE["存储层：MySQL / Redis / OSS / ChromaDB"]

    FE --> GW
    GW --> BIZ
    GW --> SCHED
    GW --> RES
    SCHED -- "RocketMQ / Kafka" --> AI
    AI --> STORE

三、职责划分

3.1 Java 侧职责

API 网关：统一入口、鉴权、限流、日志
用户与任务管理：用户注册登录、任务创建、任务状态机、历史记录
素材元数据管理：素材上传、分类、标签、权限
支付与计费（如有）：订单、套餐、用量统计
任务调度：把渲染/生成任务发送到消息队列
实时通知：SSE 推送任务进度给用户

3.2 Python 侧职责

AI Agent 编排：ReAct 任务规划、Tool 调用
RAG 检索：Embedding 计算、向量库查询
语音识别：Whisper 转写
语音合成：TTS 配音
视频渲染：Remotion 组件化渲染
后处理：FFmpeg 转码、压缩、字幕、多分辨率输出

3.3 边界原则

我们定了几条原则来避免职责混乱：

Python 不直接暴露给用户。所有用户请求都走 Java API。
Python 只做无状态计算。任务状态、用户信息、素材元数据都在 Java 侧维护。
通信以异步为主。AI 任务通常耗时较长，同步调用容易导致超时和耦合。
数据以 ID 为纽带。Java 和 Python 之间不传大对象，只传任务 ID 和必要参数。

四、服务间通信

4.1 异步通信：RocketMQ

AI 生成和渲染任务都走 RocketMQ：

// Java 侧发送任务
SendResult result = rocketMQTemplate.syncSend(
    "video-render",
    MessageBuilder.withPayload(taskMessage).build()
);

# Python 侧消费任务
class RenderConsumer:
    def on_message(self, msg):
        task = json.loads(msg.body)
        result = render_engine.process(task)
        self.update_task_status(task["task_id"], "completed", result)
        return ConsumeStatus.CONSUME_SUCCESS

异步通信的优点：

解耦 Java 和 Python 服务
Python Worker 可以独立扩缩容
任务失败可以重试，不阻塞主流程

4.2 同步通信：HTTP / gRPC

少数场景需要同步调用，比如：

查询 RAG 素材（用户在前端点击「生成」前希望看到素材推荐）
获取任务实时状态
健康检查

我们主要用 HTTP REST，因为：

简单直观，Java 和 Python 生态都完善
调试方便，curl 即可测试
对延迟要求不极端

gRPC 我们也考虑过，但因为团队对 gRPC 熟悉度不高，且收益不明显，暂时没引入。

4.3 数据一致性

双栈架构下，任务状态是核心数据。我们用数据库作为唯一真相源：

flowchart TD
    A["用户提交任务"] --> B["Java 写入任务记录（status=pending）"]
    B --> C["发送 RocketMQ 消息"]
    C --> D["Python Worker 消费"]
    D --> E["Python 更新任务状态（status=processing/completed/failed）"]

Python Worker 更新数据库时，通过乐观锁防止并发冲突：

UPDATE render_task
SET status = 'processing',
    worker_id = 'worker-01',
    updated_at = NOW()
WHERE task_id = 'xxx'
  AND status = 'pending'

五、数据库设计

5.1 按服务分库还是分表？

我们没有完全按微服务分库，而是按业务域分表：

user：用户信息
task：生成任务
material：素材元数据
template：视频模板
subscription：订阅/套餐

所有表都在一个 MySQL 实例里，通过业务 ID 关联。这种方案在业务量不大时性价比最高，未来可按域拆分。

5.2 Python 侧如何访问数据库

Python 侧需要读取/更新任务状态，我们用的是 SQLAlchemy + 只读/写分离：

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("mysql+pymysql://user:pass@host/db")
Session = sessionmaker(bind=engine)

def update_task_status(task_id: str, status: str):
    with Session() as session:
        session.execute(
            "UPDATE render_task SET status = %s WHERE task_id = %s",
            (status, task_id)
        )
        session.commit()

为了降低耦合，Python 侧只更新少量任务状态字段，不碰业务核心表。

六、部署与运维

6.1 容器化

两个栈都用 Docker 打包：

# Java 服务 Dockerfile
FROM eclipse-temurin:17-jdk
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# Python Worker Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "worker.py"]

6.2 CI/CD

我们用一个简单的 GitHub Actions / Jenkins 流程：

代码提交触发构建
分别构建 Java 镜像和 Python 镜像
推送到镜像仓库
生产环境滚动更新

6.3 日志与链路追踪

双栈环境下，排查问题最大的难点是链路跨语言。我们的做法：

所有请求携带 trace_id
Java 和 Python 都把 trace_id 打到日志里
用 ELK / Loki 做日志聚合，按 trace_id 查询全链路

import logging

logger = logging.getLogger(__name__)

logger.info("Start render", extra={"trace_id": trace_id, "task_id": task_id})

6.4 监控告警

层级	监控项
Java 服务	JVM 内存、GC、接口响应时间、错误率
Python Worker	CPU/GPU 利用率、任务处理速率、队列堆积
数据库	连接数、慢查询
消息队列	堆积量、消费速率

七、踩过的坑

7.1 序列化不一致

Java 侧用 Jackson，Python 侧用默认 json，时间格式、枚举值、空值处理不一致，导致接口对接时经常报错。

解决：

统一用 ISO 8601 时间格式
枚举值用字符串传递
制定统一的 JSON Schema，用 Pydantic 和 Java Bean Validation 双向校验

7.2 Python 服务内存泄漏

Python Worker 长时间运行后，内存占用越来越高，尤其是加载大模型后。

解决：

Worker 处理一定数量任务后自动重启
模型用单例模式加载，避免重复初始化
显式清理大对象，调用 gc.collect()

7.3 跨语言异常处理

Python 异常信息传到 Java 侧变成一团乱码，前端无法友好展示。

解决：

定义统一的错误码体系
Python 捕获异常后按规范封装错误响应
Java 侧根据错误码映射为用户友好的提示

7.4 开发环境复杂度

开发时需要同时启动 Java 服务、Python Worker、MySQL、Redis、RocketMQ，新成员上手成本高。

解决：

提供 docker-compose.yml 一键启动基础设施
编写本地开发文档
支持 Windows 开发环境降级（Python Worker 用 HTTP 模拟 RocketMQ）

八、双栈架构的收益与代价

8.1 收益

方面	说明
团队分工清晰	Java 工程师做业务，Python 工程师做 AI
技术选型合理	每个栈都用最合适的工具
稳定性高	业务系统独立演进，AI 故障不直接影响用户注册/支付
扩展灵活	Python Worker 可以根据渲染负载单独扩容

8.2 代价

方面	说明
运维复杂	两套构建、部署、监控体系
链路排查难	跨语言日志追踪需要额外设计
接口契约维护	Java 和 Python 之间需要稳定的 API 契约

九、什么情况下不要双栈？

虽然双栈适合我们，但不是所有项目都需要：

纯业务系统：全 Java 即可
纯模型研究/实验：全 Python 即可
团队规模小：双栈会增加认知负担
MVP 早期：先用最熟悉的栈跑通，后期再拆分

我们是在产品验证基本跑通、团队有 5 人以上时才明确拆成双栈。

十、总结

Spring Boot + Python 双栈不是最优架构，而是适合我们团队能力和业务形态的架构。几个关键经验：

职责边界要清晰，否则双栈会变成双倍的混乱。
异步通信是主力，同步只用于低延迟查询场景。
数据库是状态的唯一真相源，避免两端各自维护状态。
日志追踪要跨语言打通，否则线上出问题很难排查。
不要为双栈而双栈，MVP 阶段先用单栈验证。

如果你也在做 Java + Python 的混合架构，欢迎交流接口契约、部署和监控的经验。

LangGraph 入门：给传统工程师的 Agent 状态与编排指南

Wed, 11 Feb 2026 11:00:00 +0800

LangGraph 入门：给传统工程师的 Agent 状态与编排指南

我做传统软件工程很多年，习惯了状态机、工作流引擎、消息队列这些确定性系统。第一次接触 LangGraph 时，我觉得它像是一个"有状态的 DAG 调度器"，只不过节点不再是跑批任务，而是调用 LLM、工具或业务逻辑。这篇文章结合我在方糖猫 AI 短视频生成平台和 GeekCast Engine 口播剪辑项目里的经验，聊聊 LangGraph 最核心的三个概念：State、任务编排、长期记忆，以及几个让调试更轻松的小技巧。

一、LangGraph 是什么？

LangGraph 是 LangChain 生态里的一个 Agent 编排框架。它和传统工作流引擎最大的区别是：它把 LLM 调用、工具调用、业务判断都看成图里的节点，节点之间通过共享的 State 对象传递信息。

你可以把它理解成：

状态机 + LLM + 工具调用 + 持久化 = LangGraph

在方糖猫里，一个短视频生成任务的流程大致是：

接收用户输入（主题、风格、素材偏好）；
ReAct Agent 规划分镜和素材需求；
检索 RAG 本地素材库；
生成脚本初稿；
检查脚本长度与平台规范；
组装渲染任务并推送到 RocketMQ；
Python Worker 拉取任务，用 Remotion + FFmpeg 渲染成片。

这个流程如果写成 LangGraph，就是一张图：每个步骤是一个节点，节点之间根据 State 里的数据决定下一步去哪。

二、State：Agent 的"工作记忆"

State 是 LangGraph 里最重要的概念。它是一个 Python 字典（或 TypedDict/Pydantic 模型），在整个图的执行过程中被所有节点共享。

一个简单的 State 定义

from typing import TypedDict, List, Optional

class VideoGenState(TypedDict):
    topic: str                    # 用户输入的主题
    style: str                    # 风格偏好
    script: Optional[str]         # 生成的脚本
    materials: List[str]          # 检索到的素材 ID
    render_task: Optional[dict]   # 渲染任务描述
    error: Optional[str]          # 错误信息

每个节点接收 State，修改 State，然后返回更新后的 State。LangGraph 会自动合并这些更新。

为什么 State 如此重要？

在传统工作流里，我们通常把中间结果写到数据库或 Redis。LangGraph 的 State 相当于一个内存中的上下文容器，让 Agent 在单轮执行里记住：

用户原始需求；
已经做过什么；
下一步该做什么；
是否有错误需要处理。

在 GeekCast Engine 里，长视频口播稿会被切分成多个 segment。每个 segment 的处理可以是一个子图，父图的 State 里保存全局信息（比如视频总时长、字幕样式），子图的 State 里保存 segment 级别的信息（比如台词、B-roll、标题卡）。这种"全局 + 局部"的 State 设计，和我们做分布式系统时的"全局配置 + 局部任务"思想是一致的。

三、任务编排：图、节点、边

LangGraph 的编排模型很直观：

节点（Node）：执行一个函数，通常是调用 LLM、工具或业务逻辑；
边（Edge）：连接两个节点，控制执行流向；
条件边（Conditional Edge）：根据 State 的内容决定下一步去哪个节点。

一个简化版的视频生成图

from langgraph.graph import StateGraph, END

builder = StateGraph(VideoGenState)

builder.add_node("plan", plan_node)           # Agent 规划
builder.add_node("retrieve", retrieve_node)   # RAG 检索素材
builder.add_node("write_script", script_node) # 写脚本
builder.add_node("check", check_node)         # 检查规范
builder.add_node("render", render_node)       # 推送渲染任务

builder.set_entry_point("plan")
builder.add_edge("plan", "retrieve")
builder.add_edge("retrieve", "write_script")
builder.add_edge("write_script", "check")

# 条件边：检查不通过则重写脚本
builder.add_conditional_edges(
    "check",
    lambda state: "rewrite" if state.get("error") else "render",
    {"rewrite": "write_script", "render": "render"}
)

builder.add_edge("render", END)
graph = builder.compile()

这个结构和传统状态机几乎一样：每个节点做完一件事，根据结果决定下一个状态。对于习惯画状态图的工程师来说，上手很快。

条件边的价值

没有条件边，LangGraph 就只是一个固定的 Pipeline。有了条件边，Agent 才能：

根据 LLM 判断决定调用哪个工具；
根据执行结果决定重试还是继续；
根据用户反馈决定是否需要人工介入。

在方糖猫里，素材检索节点之后，如果召回的素材数量不足，我们会走"放宽检索条件"的分支；如果素材足够，才进入脚本生成。这种动态决策能力，是 LangGraph 比简单 Pipeline 更适合 Agent 场景的原因。

四、长期记忆：从单线程到跨会话

LangGraph 的持久化分为两层，这是很多人刚开始会混淆的地方：

能力	Checkpointer	Store（Memory Store）
作用范围	单个线程（`thread_id`）	跨线程、跨会话
保存内容	执行过程中的 State 快照	用户事实、交互经验、行为偏好
典型用途	断点续跑、人在回路、time-travel	长期记忆、个性化
存储示例	`InMemorySaver`、`PostgresSaver`	`InMemoryStore`、`PostgresStore`

Checkpointer：线程级的"短期记忆"

Checkpointer 让 LangGraph 可以在任意节点暂停、恢复、回溯。这对于"人在回路"（Human-in-the-loop）场景特别重要。

比如视频生成任务里，脚本生成节点完成后，我们可以让系统停下来，等用户确认脚本内容，确认后再继续渲染。没有 Checkpointer，这种中断-恢复就很难优雅实现。

from langgraph.checkpoint.memory import MemorySaver

graph = builder.compile(checkpointer=MemorySaver())

Store：真正的长期记忆

Store 是 LangGraph 为长期记忆设计的存储层。吴恩达和 Harrison Chase 在《Long-Term Agentic Memory with LangGraph》课程里，把长期记忆分为三类：

语义记忆（Semantic Memory）

存储关于用户的稳定事实，比如"用户偏好科技感风格"、“用户通常发布横屏视频”。
情景记忆（Episodic Memory）

存储具体交互案例，比如"上次用户拒绝了这个 BGM，后来换成了另一首"。这些案例可以作为 few-shot 示例，帮助 Agent 在未来做出类似判断。
程序记忆（Procedural Memory）

存储 Agent 自身应该遵循的行为模式，也就是系统提示词或判断标准的优化版本。比如"对于这类用户，生成脚本前要先确认时长"。

在项目中怎么落地？

在方糖猫里，我们目前主要用了语义记忆：把用户确认过的风格偏好、常用素材、发布平台规格等写入 Store，下次用户再创建视频时，Agent 会先读取这些记忆，减少重复确认。

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

# 在某个节点里写入记忆
store.put(
    ("user_123", "preferences"),
    "style",
    {"preferred_style": "tech", "aspect_ratio": "16:9"}
)

# 后续会话中读取
memories = store.search(("user_123", "preferences"), query="风格偏好")

生产环境建议用 PostgresStore，并把记忆更新放到后台节点执行，避免阻塞主流程。

五、实战小技巧

1. 用图片/Mermaid 输出流程图

LangGraph 编译后的图可以用 Mermaid 或图片方式可视化。这在设计阶段特别有用，尤其是在团队沟通时。

from IPython.display import Image, display

display(Image(graph.get_graph().draw_mermaid_png()))

如果你没有 Jupyter 环境，也可以输出 Mermaid 文本：

print(graph.get_graph().draw_mermaid())

然后贴到支持 Mermaid 的编辑器（比如 Notion、GitHub、Draw.io）里查看。这个习惯能帮你在写代码前先确认流程没有死循环或遗漏分支。

2. 打印提示词调试

LangGraph 节点里经常会拼接复杂的 Prompt。调试时，把最终发给 LLM 的完整 Prompt 打印出来，比看代码直观得多。

def plan_node(state: VideoGenState):
    prompt = build_plan_prompt(state)
    print("\n===== PLAN PROMPT =====\n")
    print(prompt)
    print("\n===== END PROMPT =====\n")
    response = llm.invoke(prompt)
    return {"plan": response.content}

相信我，80% 的"模型表现不好"问题，打印完 Prompt 就会发现：上下文缺失、格式混乱、或者约束互相矛盾。

3. 把节点拆小，便于追踪

一个大节点里做太多事，调试和复用都困难。我建议每个节点只负责一个明确职责：

一个节点做 LLM 调用；
一个节点做工具调用；
一个节点做 State 校验；
一个节点做错误处理。

在 GeekCast Engine 里，我们把"口播精剪"拆成了：Whisper 转写 → 时间轴分析 → 删除气口 → 重新对齐 → 输出剪辑点。每个节点都可以单独测试、单独复用。

4. 用 State 的字段做日志锚点

给 State 加上 logs 或 trace 字段，在每个节点记录关键信息。这样出问题后，可以直接看 State 快照定位到哪个节点、哪个决策点出错。

class VideoGenState(TypedDict):
    # ... 其他字段
    logs: List[str]

def retrieve_node(state):
    materials = search_materials(state["topic"])
    logs = state.get("logs", [])
    logs.append(f"retrieve: found {len(materials)} materials")
    return {"materials": materials, "logs": logs}

5. 不要忽视错误分支

LangGraph 的图很容易画成"理想路径"，但生产环境必须考虑异常：LLM 返回格式错误、工具调用超时、检索结果为空、State 校验失败。

我的做法是：每个可能失败的节点后面都跟一个错误处理节点，或者把错误信息写入 State，由条件边统一路由到重试或人工审核。

六、LangGraph 适合什么场景？

不是每个 LLM 应用都需要 LangGraph。如果你只是做一个简单的聊天机器人或单次文本生成，直接调 API 可能更轻量。

但当你遇到以下情况时，LangGraph 会很有价值：

任务需要多步骤决策，且步骤之间有依赖；
需要调用多个工具，并根据中间结果动态选择；
需要支持中断、人工确认、断点续跑；
需要长期记忆来提供个性化体验；
团队需要把 Agent 流程可视化、可维护。

方糖猫和 GeekCast Engine 都属于这类场景。LangGraph 让我们把原本散落在代码各处的"if-else + LLM 调用 + 工具调用"统一成了可看的、可调的、可持久化的图。

七、总结

LangGraph 不是另一个"让代码更复杂"的框架，而是把 Agent 执行过程显性化的工具。它的核心概念其实和传统工程很像：

State 就是工作记忆或上下文容器；
图编排 就是状态机加上动态分支；
Checkpointer 提供会话内的断点续跑；
Store 提供跨会话的长期记忆。

对于传统工程师来说，最值得培养的能力不是背 API，而是：

如何把业务问题拆成清晰的节点和状态；
如何设计 State，让它既能表达业务语义，又便于调试；
什么时候用短期记忆，什么时候用长期记忆；
如何通过可视化和小技巧降低系统的认知复杂度。

如果你正在用 LangGraph 做项目，我的建议是：先画图，再写代码；先打印 Prompt，再调模型；先把主流程跑通，再逐步加入记忆和异常处理。

我在 ftmao.com/blog 持续记录 AI Agent、LangGraph 和多模态生成相关的工程实践，欢迎关注和交流。

LangChain 入门笔记：AI 视频生成实战

Fri, 28 Nov 2025 11:00:00 +0800

LangChain 入门笔记：AI 视频生成实战

最近重新刷了吴恩达和 Harrison Chase 主讲的《LangChain for LLM Application Development》。这门课不长，但把 LangChain 的"为什么存在"讲得很透：它不是让你写更多胶水代码，而是把 LLM 调用、提示工程、上下文管理、工具调用这些重复模式抽象成可组合的组件。这篇文章整理课程里的核心原理，并落到我们最熟悉的 AI 视频生成场景，给出可直接跑的 Demo。

一、LangChain 解决什么问题？

在直接调用 OpenAI / Claude / 国产大模型 API 时，我们通常会写出这样的代码：

import openai

messages = [
    {"role": "system", "content": "你是一位短视频脚本专家。"},
    {"role": "user", "content": "主题是'如何用 LangChain 生成视频脚本'，风格轻松，30 秒左右。"}
]
resp = openai.chat.completions.create(model="gpt-4o", messages=messages)
script = resp.choices[0].message.content

这段代码能跑，但问题很明显：

提示词散落在各处，难以复用和版本管理；
输出是字符串，需要手写解析逻辑；
多轮对话、上下文记忆要自己拼 messages；
一旦涉及"检索素材 → 生成脚本 → 检查合规 → 输出结构化数据"，代码就会迅速膨胀成面条。

LangChain 的核心思想：把 LLM 应用里的常见模式抽象成标准组件，让你像搭积木一样拼装工作流。

可以把它理解成：

LangChain = 模型接口统一层 + 提示模板 + 输出解析 + 记忆 + 链式调用 + 工具/Agent 编排

二、课程核心内容回顾

吴恩达这门课围绕 6 个模块展开，也是 LangChain 最基础的 6 个能力：

模块	作用	视频生成场景映射
Models	统一不同 LLM 的调用接口	切换 GPT-4o / Claude / 国产模型时无需改业务代码
Prompts	模板化管理提示词	脚本生成、分镜描述、标题优化的模板复用
Output Parsers	把自然语言输出转成结构化数据	解析 JSON 分镜、时间轴、素材清单
Memory	维护多轮对话状态	用户反复修改脚本时保留上下文
Chains	把多个 LLM/工具步骤串成链	“主题 → 大纲 → 脚本 → 分镜 → 渲染参数"流水线
Agents	让 LLM 决定调用哪些工具	Agent 自主判断需要检索素材还是生成画面描述

下面逐一看原理和代码。

三、核心组件原理与示例

3.1 Models & Prompts：统一接口与模板复用

LangChain 用 ChatOpenAI、ChatAnthropic 等类封装模型，并用 ChatPromptTemplate 管理提示词模板。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位短视频脚本专家，擅长把技术概念写成{style}风格的口播脚本。"),
    ("human", "主题是：{topic}，时长控制在{duration}秒，需要{scene_count}个分镜。")
])

messages = prompt.invoke({
    "style": "轻松幽默",
    "topic": "LangChain 如何自动生成视频脚本",
    "duration": 30,
    "scene_count": 3
})

response = llm.invoke(messages)
print(response.content)

好处：

提示词与业务数据解耦，模板可复用、可版本化；
切换模型只需改一行 ChatOpenAI → ChatAnthropic；
支持批量 batch、流式 stream、异步 ainvoke 等高级调用方式。

3.2 Output Parsers：从文本到结构化数据

视频生成流程需要结构化输出，例如：

{
  "scenes": [
    {"time": "0-10s", "narration": "...", "visual": "...", "bgm": "..."}
  ],
  "title": "...",
  "tags": ["..."]
}

LangChain 提供 PydanticOutputParser，让模型按指定 Schema 输出。

from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import PromptTemplate

class Scene(BaseModel):
    time_range: str = Field(description="时间区间，如 0-10s")
    narration: str = Field(description="口播文案")
    visual: str = Field(description="画面描述，用于后续生成图片/视频")
    bgm_mood: str = Field(description="背景音乐情绪")

class VideoScript(BaseModel):
    title: str
    scenes: list[Scene]
    tags: list[str]

parser = PydanticOutputParser(pydantic_object=VideoScript)

prompt = PromptTemplate(
    template="根据主题生成短视频脚本。\n{format_instructions}\n主题：{topic}\n时长：{duration}秒\n",
    input_variables=["topic", "duration"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

chain = prompt | llm | parser
result = chain.invoke({"topic": "LangChain 自动生成短视频", "duration": 30})
print(result.model_dump_json(indent=2))

注意：LLM 不一定 100% 返回合法 JSON，生产环境建议加 RetryOutputParser 或兜底解析。

3.3 Memory：多轮修改不再"失忆”

做视频脚本时，用户常会说：“前面不错，但把第二段改得更口语化一点”。没有记忆，LLM 会从头生成，丢失已确认的片段。

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

memory = ConversationBufferMemory()
conversation = ConversationChain(llm=llm, memory=memory)

conversation.predict(input="帮我写一个 30 秒的 LangChain 短视频脚本")
conversation.predict(input="第二段太正式了，改成口语化一些")
print(memory.load_memory_variables({}))

LangChain 还提供 ConversationBufferWindowMemory（只保留最近 N 轮）、ConversationSummaryMemory（摘要历史）等，适用于长会话场景。

3.4 Chains：把多个步骤串成流水线

视频生成的一个典型链：

主题 → 生成标题 → 生成脚本 → 生成分镜 → 输出结构化渲染参数

用 LCEL（LangChain Expression Language）可以非常直观地表达：

from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 子链 1：生成标题
title_prompt = ChatPromptTemplate.from_template("为'{topic}'写一个 20 字以内的爆款标题")
title_chain = title_prompt | llm | StrOutputParser()

# 子链 2：根据标题和主题生成脚本
script_prompt = ChatPromptTemplate.from_template(
    "标题：{title}\n主题：{topic}\n时长：{duration}秒\n请生成 3 个分镜的脚本。"
)
script_chain = script_prompt | llm | StrOutputParser()

# 组合
full_chain = (
    {"topic": RunnablePassthrough(), "duration": RunnablePassthrough()}
    | RunnablePassthrough.assign(title=title_chain)
    | RunnablePassthrough.assign(script=script_chain)
)

result = full_chain.invoke({"topic": "LangChain 视频生成", "duration": 30})
print(result)

LCEL 的 | 运算符让数据流像 Unix 管道一样清晰，这也是 LangChain 从 0.1 到 0.2/0.3 版本最重要的设计演进。

3.5 RAG：用本地素材库增强脚本生成

做批量短视频时，通常有沉淀的素材库（文案库、分镜库、音乐库）。LangChain 的 RAG 组件可以让模型先检索再生成：

from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain.chains.combine_documents import create_stuff_documents_chain

# 1. 构建向量库
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_texts(
    ["分镜案例 1：开头用悬念钩子...", "爆款标题公式：数字+痛点+解决方案..."],
    embedding=embeddings
)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

# 2. 构建 RAG Chain
prompt = ChatPromptTemplate.from_messages([
    ("system", "参考以下素材生成脚本：\n\n{context}"),
    ("human", "主题：{topic}，时长：{duration}秒")
])

rag_chain = create_stuff_documents_chain(llm, prompt) | {
    "topic": lambda x: x["topic"],
    "context": retriever
}

# 实际调用时先检索文档，再塞入 prompt

在方糖猫 AI 短视频平台的工程实现中，我们会把 RAG 检索结果和 LangGraph 状态机结合，实现"检索 → 生成 → 人工审核 → 渲染"的完整闭环。

3.6 Agents：让 LLM 自己决定下一步

当流程不是固定流水线，而是需要动态决策时，Agent 更有优势。例如：

判断用户输入是否需要检索素材库；
根据脚本内容决定调用文生图还是文生视频工具；
调用外部 API 查询热点话题。

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.tools import tool

@tool
def generate_image(description: str) -> str:
    """根据画面描述生成一张图片，返回图片 URL。"""
    # 实际接入 DALL·E / Midjourney / Stable Diffusion
    return f"https://fake-img.example.com?prompt={description}"

@tool
def generate_video_clip(description: str, duration: int) -> str:
    """根据画面描述生成一段视频片段，返回视频 URL。"""
    return f"https://fake-video.example.com?prompt={description}&duration={duration}"

tools = [generate_image, generate_video_clip]

agent_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位 AI 视频导演，能调用工具生成图片或视频。"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}")
])

agent = create_openai_tools_agent(llm, tools, agent_prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

agent_executor.invoke({
    "input": "我要一个 30 秒关于 LangChain 的短视频，先出 3 张分镜图，再合成视频。"
})

四、Demo：一个可扩展的"AI 视频脚本生成器"

下面把上面所有组件串起来，做一个最小的可运行 Demo。它的输出是一份结构化脚本，后续可以无缝接到 Remotion、FFmpeg 或视频生成 API。

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.runnables import RunnablePassthrough
from pydantic import BaseModel, Field

os.environ["OPENAI_API_KEY"] = "your-api-key"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)

class Scene(BaseModel):
    time_range: str
    narration: str
    visual: str
    tool: str = Field(description="生成该分镜所需工具：image 或 video")

class VideoProject(BaseModel):
    title: str
    target_platform: str
    scenes: list[Scene]

parser = PydanticOutputParser(pydantic_object=VideoProject)

title_chain = (
    ChatPromptTemplate.from_template("为'{topic}'写一个适合{platform}的爆款标题")
    | llm
    | StrOutputParser()
)

script_prompt = ChatPromptTemplate.from_template(
    """为平台"{target_platform}"生成短视频脚本。
{format_instructions}
标题：{title}
主题：{topic}
时长：{duration}秒
要求：每个分镜标注用 image（图片）还是 video（视频片段）生成。
"""
)

script_chain = (
    RunnablePassthrough.assign(title=title_chain)
    | script_prompt.partial(format_instructions=parser.get_format_instructions())
    | llm
    | parser
)

project = script_chain.invoke({
    "topic": "LangChain 如何帮助 AI 视频创作",
    "platform": "抖音",
    "target_platform": "抖音",
    "duration": 30
})

print(project.model_dump_json(indent=2, ensure_ascii=False))

下一步可以扩展的方向：

把 Scene.visual 传给 DALL·E / Stable Diffusion / 可灵 / Pika 生成画面；
用 pydub + gTTS 合成配音，或用 CosyVoice 克隆音色；
用 Remotion 或 MoviePy 把图片、视频、字幕、BGM 合成为成片；
接入 LangGraph 做状态持久化和人工审核节点（参考我之前写的 LangGraph 入门笔记）。

五、分布式场景下的运行方案

当 LangChain 应用从本地脚本走向生产环境，单进程运行肯定不够。AI 视频生成是典型的长链路任务：脚本生成、素材检索、文生图、文生视频、配音、渲染，每一步都可能耗时数秒到数分钟。分布式架构的关键是：让 LangChain 推理层保持无状态，把状态交给任务队列和持久化存储。

关键设计点

LangChain 服务无状态化 不保存用户会话到本地内存，所有上下文通过 state 参数或 Redis 传入。这样任意 Worker 都可以处理任意任务，方便水平扩展。
任务队列解耦 用 Celery、RQ 或自研 Worker 消费 RocketMQ/Redis Stream。一个任务对应一次视频生成链路，失败可以重试，不会阻塞 API 网关。
持久化中间状态 把每个阶段的结果（脚本 JSON、分镜图 URL、视频片段 URL）写入数据库。如果 Worker 崩溃，可以从上一个阶段恢复，而不是从头执行。
LangGraph 的分布式友好性 LangGraph 的 State 天然适合持久化。可以配置 checkpointer 把状态快照到 Redis/Postgres，实现断点续跑：

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

builder = StateGraph(VideoGenState)
# ... 添加节点和边 ...
graph = builder.compile(checkpointer=MemorySaver())

生产环境建议把 MemorySaver 替换为 PostgresSaver 或 RedisSaver，让不同 Worker 共享状态。

六、服务器异常恢复方案

AI 视频生成链路长、依赖多（LLM API、素材库、视频生成服务、对象存储），任何一环抖动都会导致失败。异常恢复不是简单 try/except，而是要从架构层面保证可观测、可重试、可续跑。

1. 分级重试策略

异常类型	处理方式	示例
LLM API 限流 / 超时	指数退避重试 3 次	`tenacity` 或 LangChain 内置 `max_retries`
第三方服务不可用	降级或转人工审核	视频生成失败时返回占位图 + 提示
Worker 进程崩溃	队列自动重发，幂等消费	Celery `acks_late=True`
数据格式错误	进入死信队列，人工处理	JSON 解析失败

LangChain 调用模型时建议统一封装：

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
def invoke_with_retry(chain, inputs):
    return chain.invoke(inputs)

2. 幂等性设计

同一个视频生成任务可能因为网络超时被重复投递。给每个任务分配唯一 task_id，在数据库里记录 PENDING → PROCESSING → SUCCESS/FAILURE 状态。Worker 消费前先看状态，避免重复执行。

def process_video_task(task_id: str, inputs: dict):
    if db.get_status(task_id) in ("SUCCESS", "PROCESSING"):
        return db.get_result(task_id)

    db.set_status(task_id, "PROCESSING")
    try:
        result = video_chain.invoke(inputs)
        db.set_status(task_id, "SUCCESS", result=result)
        return result
    except Exception as e:
        db.set_status(task_id, "FAILURE", error=str(e))
        raise

3. 死信队列（DLQ）

重试仍然失败的任务进入死信队列，由告警系统通知运维或产品人员处理。DLQ 里的任务可以手动重跑、补数据或退款。

4. 状态快照与断点续跑

结合 LangGraph 的 checkpointer，每个节点执行完后自动保存状态。Worker 重启后，可以根据 thread_id 恢复到最近的 checkpoint：

config = {"configurable": {"thread_id": task_id}}
# 首次执行
graph.invoke(initial_state, config=config)

# Worker 重启后继续执行
state = graph.get_state(config)
graph.invoke(None, config=config)  # 从 checkpoint 继续

七、如何实现高并发

AI 视频生成场景的高并发，核心矛盾是：LLM API 调用有速率限制，但用户请求可能突增。不能简单堆机器，需要把 IO 等待和计算分离。

1. 异步调用释放线程

LangChain 支持 ainvoke、abatch、astream，配合 asyncio 可以大幅提升吞吐：

import asyncio

async def batch_generate(tasks):
    results = await script_chain.abatch(tasks)
    return results

# 并发处理 20 个脚本生成请求
tasks = [{"topic": t, "duration": 30} for t in topic_list]
results = asyncio.run(batch_generate(tasks))

注意：底层 HTTP 客户端（如 httpx）需要配置连接池，避免每次请求新建连接。

2. 流式响应降低首字节延迟

对于长文本生成，使用 astream 把结果逐步返回给用户，避免长时间阻塞：

async for chunk in chain.astream({"topic": "LangChain 高并发"}):
    print(chunk, end="", flush=True)

3. 限流与背压

模型侧限流：根据 OpenAI/Claude 的 RPM/TPM 限制，用令牌桶算法控制请求速率。
队列侧背压：当队列堆积超过阈值时，API 网关返回 429 Too Many Requests，保护下游 Worker。

import asyncio
from asyncio import Semaphore

sem = Semaphore(10)  # 同时最多 10 个 LLM 调用

async def limited_invoke(inputs):
    async with sem:
        return await chain.ainvoke(inputs)

4. 缓存常用结果

很多提示词是重复的（比如热门模板、常见分镜描述）。可以用 Redis 缓存 prompt_hash → result，命中时直接返回，不走 LLM：

import hashlib

def get_cache_key(inputs: dict) -> str:
    return hashlib.sha256(json.dumps(inputs, sort_keys=True).encode()).hexdigest()

key = get_cache_key(inputs)
if cached := redis.get(key):
    return json.loads(cached)

result = chain.invoke(inputs)
redis.setex(key, 3600, json.dumps(result))

5. 水平扩展与资源隔离

CPU 密集型步骤（如 FFmpeg 渲染、图片后处理）放到独立 Worker 池，避免阻塞 LLM 推理线程。
GPU 密集型步骤（如文生视频）单独部署 GPU 节点，通过队列按需调度。
API 网关层用 Nginx/Envoy 做负载均衡，无状态 LangChain 服务可以快速扩容。

八、学完这门课的几点体会

不要神化 LangChain：它本质是高阶胶水，帮你少写重复代码，但不会让模型变得更聪明。复杂的业务逻辑仍然需要自己设计。
优先用 LCEL：新项目中尽量用 Runnable + | 组合链，比旧的 LLMChain、SequentialChain 更灵活、更易调试。
结构化输出是工程关键：视频、电商、客服等场景都需要把 LLM 输出转成 JSON，PydanticOutputParser 是必备技能。
Agent 不是银弹：固定流程用 Chain，动态决策才用 Agent。Agent 调试成本高，要配合观察日志和工具描述优化。

九、参考资源

吴恩达 & Harrison Chase 官方课程：LangChain for LLM Application Development
中文笔记与代码：awesome-LangChain-for-LLM-Application-Development
我之前的相关笔记：LangGraph 入门：给传统工程师的 Agent 状态与编排指南

这篇文章把吴恩达课程的核心内容和我自己在 AI 视频生成项目里的经验做了结合。如果你也在用 LangChain 做视频、口播剪辑或 Agent 工作流，欢迎留言交流。

《算法与数据结构》教材学习笔记：一张地图看懂全书，附避坑技巧与典型题

Sat, 12 Nov 2022 10:30:00 +0800

《算法与数据结构》教材学习笔记

目标读者：正在学（或补）大学《算法与数据结构》这门课的新人。阅读目标：看完能对全书有一个整体地图；知道每种结构"什么时候用、怎么实现、容易踩什么坑"；能用简单代码解决典型问题。代码说明：实现采用 Python（简洁易懂、贴近伪代码），但思路与语言无关。

0. 开篇：这门课到底在讲什么

《算法与数据结构》整本书其实只回答一个问题：如何把"数据"组织起来，让"操作"更快。

教材里的任何一章，都可以拆成三句话：

逻辑结构：数据之间的关系（线性、树形、图状、集合）。
存储结构：这些关系在内存里怎么放（顺序存储 / 链式存储 / 散列存储）。
运算（算法）：在这种组织方式上怎么做增删改查，效率如何。

flowchart TD
    A[现实世界的问题] --> B[抽象出逻辑结构]
    B --> C{选存储结构}
    C --> C1[顺序存储<br/>连续内存, 随机访问快]
    C --> C2[链式存储<br/>指针串联, 增删快]
    C --> C3[散列存储<br/>哈希函数, 查找接近O1]
    C --> D[设计运算/算法]
    D --> E[用复杂度评估好坏]
    E --> F[得到可执行的程序]

新人最容易犯的错误，是上来就背代码。正确顺序是：先想清楚逻辑关系 → 再选存储方式 → 最后才是写算法。

评判算法好坏的尺子只有两个：

时间复杂度：操作次数随输入规模 n 增长的趋势（O(1) < O(log n) < O(n) < O(n log n) < O(n²) < O(2ⁿ)）。
空间复杂度：额外占用了多少内存。

避坑 #0：复杂度看的是"趋势"不是"精确次数"。O(2n+100) 就是 O(n)，常数和低阶项全部扔掉。

1. 全书知识地图

flowchart LR
    subgraph 基础["数据结构部分"]
        L1[线性表<br/>顺序表/链表]
        L2[栈与队列<br/>受限线性表]
        L3[串与数组<br/>KMP/特殊矩阵]
        L4[树<br/>二叉树/BST/赫夫曼/B树]
        L5[图<br/>遍历/最短路/生成树]
    end
    subgraph 算法["算法部分"]
        A1[查找<br/>顺序/二分/哈希]
        A2[排序<br/>插入/交换/选择/归并]
        A3[算法思想<br/>递归/分治/贪心/动态规划]
    end
    基础 --> 算法
    L1 --> L2 --> L3 --> L4 --> L5
    L4 --> A1
    L3 --> A2

学习主线一句话：线性表是地基，栈队列是线性表的特例，树和图是推广，查找和排序是应用，递归分治等思想贯穿始终。

2. 线性表：一切的起点

2.1 什么时候用哪种

	顺序表（Python 的 list）	链表
随机访问第 i 个	O(1)	O(n)
中间插入/删除	O(n)（要搬数据）	O(1)（找到位置后）
内存	连续，按需自动扩容	分散，逐个结点申请
典型场景	频繁按下标读、长度稳定	频繁增删、长度不确定

一句话场景判断：“读多写少用数组，增删多用链表”。（Python 的 list 是动态数组，自带扩容；教材里的链表则要自己定义结点类。）

2.2 单链表结构与操作图解

flowchart LR
    head[头指针] --> H((头结点))
    H --> A1[a₁] --> A2[a₂] --> A3[a₃] --> NULL[∅ None]

在结点 p 之后插入新结点 s，顺序不能反：

sequenceDiagram
    participant s as 新结点s
    participant p as 结点p
    participant n as p.next
    Note over s,n: 第一步: s.next = p.next (先接上后面)
    s->>n: s 指向 p 的后继
    Note over s,p: 第二步: p.next = s (再让 p 指向 s)
    p->>s: p 指向 s

避坑 #1：插入时如果先写 p.next = s，原来 p.next 指向的结点就丢了（断链）。永远先接后继，再改前驱。

2.3 简单实现：单链表反转

链表反转是理解指针（引用）操作的"Hello World"，也是面试必考：

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def reverse_list(head: ListNode) -> ListNode:
    """原地反转单链表，返回新的头结点"""
    prev, cur = None, head
    while cur:
        nxt = cur.next   # 1. 先记住下一个，防止断链
        cur.next = prev  # 2. 掉头
        prev = cur       # 3. prev 前进
        cur = nxt        # 4. cur 前进
    return prev          # prev 停在原尾结点，即新头

避坑 #2：所有链表题，先建一个"虚拟头结点"（dummy node），可以让"删除头结点"和"删除中间结点"用同一套代码，不用特判，错误率直线下降。避坑 #3：引用操作完一定要检查边界：对 None 取 .next 会报 AttributeError，循环里每一步都问自己"这个引用可能是 None 吗"。

3. 栈与队列：加了规矩的线性表

flowchart LR
    subgraph 栈Stack["栈：后进先出 LIFO"]
        direction TB
        in1[入栈 push] --> top
        top[栈顶 top] --> out1[出栈 pop]
    end
    subgraph 队列Queue["队列：先进先出 FIFO"]
        direction LR
        rear[队尾 rear<br/>入队] --> q1[...] --> front[队首 front<br/>出队]
    end

3.1 场景速查

栈：括号匹配、表达式求值、函数调用栈、DFS、撤销（Undo）、浏览器后退。Python 里直接用 list，append() 入栈、pop() 出栈。
队列：BFS、消息队列、缓冲区、按层处理（如二叉树层序遍历）。Python 里用 collections.deque，append() 入队、popleft() 出队（不要用 list.pop(0)，那是 O(n)）。

判断口诀：“后进先出想栈，排队公平想队列”。

3.2 简单实现：括号匹配

def is_match(s: str) -> bool:
    """判断字符串中的 () [] {} 是否匹配"""
    pairs = {')': '(', ']': '[', '}': '{'}
    stack = []
    for c in s:
        if c in '([{':
            stack.append(c)          # 左括号入栈
        elif c in ')]}':
            if not stack:            # 坑：栈空还来右括号
                return False
            if stack.pop() != pairs[c]:
                return False
    return not stack                 # 坑：别忘了栈里可能剩左括号

避坑 #4：括号匹配的两个经典漏判——栈空时遇到右括号（如 ")("）和遍历完栈非空（如 "((("）。考试和面试最爱在这两个地方埋雷。避坑 #5：顺序队列用定长数组实现时会有"假溢出"（rear 到顶但前面有空位），解法是把数组首尾相接做成循环队列，用 (rear+1) % MAXSIZE == front 判满。（Python 的 deque 内部已处理好这个问题，但考试按教材的循环队列答。）

4. 串与 KMP：让字符串匹配不回退

朴素的字符串匹配：主串指针 i 每次失配都要回退，最坏 O(n·m)。

KMP 的核心思想一句话：失配时利用"已匹配部分的前后缀相同"信息，让主串指针 i 永不回退，只移动模式串指针 j，复杂度降到 O(n+m)。

flowchart TD
    A[i 指向主串, j 指向模式串] --> B{"s[i] == p[j] ?"}
    B -- 相等 --> C[i++, j++]
    B -- 不等且 j>0 --> D["j = next[j]<br/>(模式串自己回退, i 不动)"]
    B -- 不等且 j==0 --> E[i++]
    C --> F{j 到达模式串末尾?}
    D --> B
    E --> B
    F -- 是 --> G[匹配成功]
    F -- 否 --> B

避坑 #6：next 数组的定义是"模式串前 j 个字符中，最长的相等真前后缀长度"。很多人背了代码却没理解这句话，换道题就不会推。手工推 next 数组是教材必考题，务必练几次。

5. 树：最重要的非线性结构

5.1 二叉树长什么样

graph TD
    A((A 根)) --> B((B))
    A --> C((C))
    B --> D((D))
    B --> E((E))
    C --> F((F))

三种遍历对同一棵树的不同访问顺序：

遍历	顺序	上图结果	典型用途
前序	根→左→右	A B D E C F	复制树、表达式前缀形式
中序	左→根→右	D B E A F C	BST 中序 = 有序序列
后序	左→右→根	D E B F C A	释放树、计算目录大小

5.2 简单实现：递归遍历

class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

def preorder(root: TreeNode):
    """前序遍历；把三行的顺序换成 LVR / LRV 就是中序/后序"""
    if root is None:         # 递归出口
        return
    visit(root)              # V：访问根
    preorder(root.left)      # L：遍历左子树
    preorder(root.right)     # R：遍历右子树

避坑 #7：树的题 90% 能用递归解决，写递归时先写递归出口（root is None），再写"我对当前结点做什么、把什么交给子树"。想不清就画一棵三层的树手动模拟。另外注意 Python 默认递归深度约 1000，树很深时要改迭代写法或调 sys.setrecursionlimit。避坑 #8：**“二叉搜索树（BST）中序遍历结果是升序”**这条性质是大量题目的钥匙——验证 BST、找第 K 小、找两结点最近公共祖先都靠它。

5.3 教材里的三种重要树

赫夫曼树：带权路径长度最短的树，用于赫夫曼编码（压缩）。构造方法：每次取权值最小的两棵合并（Python 里用 heapq 实现非常顺手）。
二叉搜索树（BST）：左子树所有值 < 根 < 右子树所有值。查找/插入/删除平均 O(log n)，但退化成链表时最坏 O(n)。
平衡二叉树（AVL）与 B 树：为了解决 BST 退化问题。AVL 靠旋转保持左右子树高度差 ≤ 1；B 树一个结点存多个关键字，矮而胖，是数据库索引和文件系统的基石。

避坑 #9：BST 删除有两个孩子的结点时，标准做法是用中序直接前驱（左子树最大）或中序直接后继（右子树最小）顶替，再删除那个顶替者。直接删会把子树搞丢。

6. 图：关系最一般的结构

6.1 怎么存

邻接矩阵：g[i][j] 表示 i 到 j 是否有边。适合稠密图，查边 O(1)，空间 O(n²)。
邻接表：每个顶点挂一个邻居列表。适合稀疏图，空间 O(n+e)，默认首选。Python 里用 dict[int, list[int]] 即可。

6.2 两种遍历

flowchart LR
    subgraph DFS["DFS 深度优先"]
        d1[访问v] --> d2[选一个未访问邻居<br/>递归深入] --> d3[无路可走才回溯]
    end
    subgraph BFS["BFS 广度优先"]
        b1[v 入队] --> b2[出队并访问] --> b3[所有未访问邻居入队] --> b2
    end

from collections import deque

def dfs(g: dict, v, visited: set):
    """DFS：递归 + visited 集合防环"""
    visited.add(v)
    visit(v)
    for w in g[v]:
        if w not in visited:
            dfs(g, w, visited)

def bfs(g: dict, s):
    """BFS：队列 + visited 集合"""
    visited = {s}
    q = deque([s])
    while q:
        v = q.popleft()
        visit(v)
        for w in g[v]:
            if w not in visited:
                visited.add(w)   # 坑：入队时就标记，不是出队时
                q.append(w)

避坑 #10：图遍历必须配 visited，漏了它遇到环就死循环。而且要在入队时（不是出队时）标记 visited，否则同一结点会被多次入队。

6.3 图的经典应用速查

问题	算法	一句话说明
无权图最短路径	BFS	按层扩展，第一次到达即最短
带权（非负）最短路	Dijkstra	每次挑当前距离最小的点"定稿"
最小生成树	Prim / Kruskal	连通所有点的最小代价（布线、修路）
课程先修顺序	拓扑排序	反复找入度为 0 的点输出
关键路径	AOE 网	工程中最长路径决定工期

6.4 简单实现：Dijkstra 最短路径

思想一句话：每次从未定稿的点里挑距离最小的点"定稿"，再用它去松弛所有出边（好比涟漪一圈圈扩散，最近的点最先确定）。用最小堆（heapq）把"挑最小"从 O(n) 降到 O(log n)，总复杂度 O((n+e) log n)。

import heapq

def dijkstra(g: dict, s) -> dict:
    """g[u] = [(v, w), ...] 表示 u->v 有一条权值为 w 的边（要求 w >= 0）
    返回 s 到各点的最短距离，不可达的点不在结果中"""
    dist = {s: 0}
    pq = [(0, s)]                      # (当前距离, 顶点)，最小堆
    done = set()                       # 已"定稿"的点
    while pq:
        d, u = heapq.heappop(pq)       # 挑出距离最小的点
        if u in done:                  # 坑：堆里可能有同一点的过期记录
            continue
        done.add(u)                    # 定稿：d 就是 s 到 u 的最短距离
        for v, w in g.get(u, []):
            if v not in done and d + w < dist.get(v, float('inf')):
                dist[v] = d + w        # 松弛：找到更短的路
                heapq.heappush(pq, (dist[v], v))
    return dist

# 示例：g = {'A': [('B', 5), ('C', 2)], 'B': [('C', 1)], 'C': [('B', 3)]}
# dijkstra(g, 'A') -> {'A': 0, 'C': 2, 'B': 5}

要点解释：

松弛：如果"经过 u 再到 v"比已知的 v 距离更短，就更新 v 的距离——dist[v] = d + w 那一行。
懒惰删除：堆里的记录可能已被更新（过期），出堆时用 done 集合跳过，避免入堆记录删不掉的麻烦。
想要具体路径而不只是距离？再维护一个 prev[v] = u 前驱字典，最后从终点倒推即可。

避坑 #11：Dijkstra 不能处理负权边（“定稿"假设一旦成立就被负边打破），有负权要用 Bellman-Ford。这是考研和面试的经典判断题。避坑 #12：拓扑排序排不完（输出点数 < 总点数）说明图中有环，工程上意味着任务依赖出现了死锁。

7. 查找

7.1 三种基本查找

方法	前提	平均复杂度	场景
顺序查找	无	O(n)	数据少、无序
二分查找	有序 + 顺序存储	O(log n)	静态有序数据
散列（哈希）查找	建哈希表	接近 O(1)	海量数据快速查询

7.2 简单实现：二分查找（正确写法）

def binary_search(a: list, key) -> int:
    """在有序数组 a 中找 key，找到返回下标，否则返回 -1"""
    l, r = 0, len(a) - 1
    while l <= r:
        mid = l + (r - l) // 2   # 通用写法，见避坑 #13
        if a[mid] == key:
            return mid
        elif a[mid] < key:
            l = mid + 1
        else:
            r = mid - 1
    return -1

避坑 #13：Python 的整数不会溢出，但 C/Java 里 mid = (l + r) / 2 在 l、r 很大时会整数溢出；统一写成 l + (r - l) // 2 是跨语言都安全的好习惯。（Python 工程代码直接用标准库 bisect 模块，但手写二分是基本功。）避坑 #14：二分的边界要全程统一——while l <= r 配 l = mid + 1 / r = mid - 1（闭区间写法），不要中途混用左闭右开的条件，否则差一错误（off-by-one）必现。

7.3 哈希的冲突处理

哈希查找快的前提是处理好冲突（两个关键字映射到同一位置）：

flowchart TD
    K[关键字 key] --> H[哈希函数 h key]
    H --> C{位置被占?}
    C -- 否 --> S[直接存放/命中]
    C -- 是 --> M1[开放定址法<br/>向后探测空位]
    C -- 是 --> M2[链地址法<br/>同位置挂链表]

开放定址法：冲突了就顺延找下一个空位（教材重点，删除要设"墓碑"标记）。
链地址法：同位置元素串成链表（工程主流，Python 的 dict 和 Java 的 HashMap 都用类似思路）。

避坑 #15：哈希表的效率取决于装填因子 α = 元素数 / 表长。α 越大冲突越多。工程上 α 超过 0.7 左右就该扩容了。

8. 排序：教材的重头戏

8.1 分类地图

flowchart TD
    S[内部排序] --> I[插入类]
    S --> X[交换类]
    S --> C[选择类]
    S --> M[归并类]
    I --> I1[直接插入 O n²]
    I --> I2[希尔排序 O n^1.3]
    X --> X1[冒泡 O n²]
    X --> X2[快速排序 O n log n<br/>平均最快]
    C --> C1[简单选择 O n²]
    C --> C2[堆排序 O n log n]
    M --> M1[归并排序 O n log n<br/>稳定]

8.2 一张表记住所有考点

排序	平均	最坏	空间	稳定?	一句话记忆
直接插入	O(n²)	O(n²)	O(1)	✅	打扑克插牌
希尔	O(n^1.3)	O(n²)	O(1)	❌	分组插入
冒泡	O(n²)	O(n²)	O(1)	✅	相邻交换，轻的浮上去
快速	O(n log n)	O(n²)	O(log n)	❌	分治：选定枢轴分两边
简单选择	O(n²)	O(n²)	O(1)	❌	每轮挑最小的放前面
堆	O(n log n)	O(n log n)	O(1)	❌	用堆反复取最值
归并	O(n log n)	O(n log n)	O(n)	✅	先分后合，合并两个有序段

避坑 #16：“稳定"指相等元素的相对顺序排序后不变。常见坑：快排、堆排、简单选择、希尔都不稳定；插入、冒泡、归并稳定。需要稳定性时（比如先按成绩排再按学号排），选归并。（Python 内置的 sorted() 是 Timsort，稳定，工程直接用它。）避坑 #17：快速排序在输入已基本有序 + 选第一个元素做枢轴时退化成 O(n²)，实际工程中要随机选枢轴或三数取中。

8.3 简单实现：快速排序

def quick_sort(a: list, l: int, r: int):
    """快排：分治思想。partition 把枢轴放到最终位置，左边都比它小，右边都比它大"""
    if l >= r:
        return
    p = partition(a, l, r)
    quick_sort(a, l, p - 1)   # 递归左半
    quick_sort(a, p + 1, r)   # 递归右半

def partition(a: list, l: int, r: int) -> int:
    pivot = a[l]              # 选首元素做枢轴（教学版）
    while l < r:
        while l < r and a[r] >= pivot:
            r -= 1
        a[l] = a[r]           # 小的补到左边
        while l < r and a[l] <= pivot:
            l += 1
        a[r] = a[l]           # 大的补到右边
    a[l] = pivot              # 枢轴归位
    return l

9. 算法思想：递归、分治、贪心、动态规划

教材后半部分的灵魂。四者关系一句话：递归是手段，分治是"拆开再合并”，贪心是"每步选当前最好”，动态规划是"记住算过的子问题别重算"。

flowchart TD
    P[大问题] --> D{能否拆成<br/>同类子问题?}
    D -- 能, 子问题独立 --> DC[分治<br/>如归并排序/快排]
    D -- 能, 子问题重叠 --> DP[动态规划<br/>存表避免重算]
    P --> G{每步局部最优<br/>能推出全局最优?}
    G -- 能 --> GR[贪心<br/>如赫夫曼/Kruskal]
    G -- 不能 --> DP

9.1 简单实现：爬楼梯（DP 入门第一题）

def climb_stairs(n: int) -> int:
    """一次爬 1 或 2 级台阶，n 级有多少种爬法？"""
    if n <= 2:
        return n
    a, b = 1, 2               # dp[1]=1, dp[2]=2
    for _ in range(3, n + 1):
        a, b = b, a + b       # dp[i] = dp[i-1] + dp[i-2]
    return b

避坑 #18：写动态规划先别动手写代码，先用一句中文说清"dp[i] 表示什么"（状态定义），再写状态转移方程。这两步想清楚了，代码是机械翻译。直接上手写代码的，十有八九死在边界初始化上。（递归版 DP 记得加 @functools.lru_cache，否则指数级重复计算。）

10. 典型问题速查表

典型问题	所属章节	解题钥匙
单链表反转 / 找倒数第 K 个结点	线性表	三指针原地反转 / 快慢指针
括号匹配、表达式求值	栈	左括号入栈，右括号出栈比对
约瑟夫问题	线性表/队列	循环链表模拟，或队列反复出队入队
汉诺塔	递归	把 n-1 个盘移到辅助柱 → 移大盘 → 再移回
判断/还原二叉树	树	前序+中序可唯一确定一棵树
求树高、叶子数	树	递归：`1 + max(左高, 右高)`
赫夫曼编码	树	每次合并最小两个权值（`heapq`）
迷宫问题	栈/DFS	栈记录路径，走不通就回溯
无权最短路	图/BFS	BFS 按层扩展
课程表能否修完	图/拓扑	拓扑排序 + 判环
前 K 大元素	堆	维护大小为 K 的小顶堆（`heapq`）
合并 K 个有序数组	归并	两两归并或堆

11. 全书避坑清单（考前/面试前过一遍）

复杂度只看最高阶，扔掉常数。
链表插入：先接后继，再改前驱；万能技巧：虚拟头结点。
括号匹配：查"栈空遇右括号"和"遍历完栈非空"两种漏判。
循环队列判满：(rear+1) % MAX == front；队列出队用 deque.popleft()。
KMP 的 next 数组要会手工推。
树的递归：先写递归出口；注意 Python 递归深度限制。
记住：BST 中序遍历 = 升序。
图遍历必须 visited，BFS 在入队时标记。
Dijkstra 不支持负权边；拓扑排不完 = 有环。
二分：mid = l + (r - l) // 2，区间定义全程统一。
哈希关注装填因子；开放定址法删除要打标记不能真删空。
快排/堆排/简单选择/希尔不稳定；快排怕有序输入。
动态规划：先说清 dp[i] 的含义，再写转移方程，最后处理初始化。

12. 学习路线建议

flowchart LR
    W1[第1-2周<br/>复杂度+线性表] --> W2[第3-4周<br/>栈/队列/串]
    W2 --> W3[第5-6周<br/>树与二叉树]
    W3 --> W4[第7-8周<br/>图]
    W4 --> W5[第9-10周<br/>查找+排序综合]

三点经验之谈：

每个结构都亲手实现一遍。看懂和会写之间隔着一条鸿沟，哪怕写得慢，也要自己敲出链表、栈、二叉树遍历、快排这"四大件"。
画图比读代码快。指针题、树题、图题，先在纸上画出结构变化，再翻译成代码，出错率低一半。
题做不出来别死磕。20 分钟没思路就看解析，重点搞懂"人家为什么想到用这个结构"，第二天独立重写一遍。吃透一类题，胜过囫囵刷一百道。

结语

《算法与数据结构》这本书看起来章节多，其实主线非常清晰：数据怎么组织（结构）→ 操作怎么实现（算法）→ 效率怎么评估（复杂度）。把这三问套到每一章，全书就从"一堆要背的知识"变成"一张可以推理的地图"。

希望这份笔记能帮你把地图先装进脑子里，剩下的，就是动手写、动手画、动手刷。

《Effective Python》深度笔记：90 个有效方法与工程实践

Mon, 05 Oct 2020 21:00:00 +0800

《Effective Python》深度笔记：90 个有效方法与工程实践

这份笔记基于 Brett Slatkin 的《Effective Python: 90 Specific Ways to Write Better Python》（第 2 版），并结合日常工程实践做了补充。与简单罗列条目不同，我尝试为每条建议补充可运行的代码片段、容易踩的坑以及落地时的判断标准，让这份笔记既能速查，也能作为团队代码评审的参考。

前置补充：一些高频但容易忽略的基础

在正式进入原著的 90 条之前，先把日常写 Python 时反复出现、但原著不会专门展开的基础点列出来，方便后续章节引用。

1. Literal 类型提示

Literal 用于限定变量只能取某些固定的字面量值，适合状态码、枚举字符串等场景。

from typing import Literal

def move(direction: Literal["up", "down", "left", "right"]) -> None:
    ...

move("up")      # OK
move("forward") # 类型检查器会报错

2. Pydantic 的 Field

用 Field 可以在数据模型里同时做校验和文档描述，比裸的 BaseModel 更适合生产接口。

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(
        ...,
        description="用户的真实姓名",
        min_length=1,
        max_length=50,
    )
    age: int = Field(
        default=18,
        ge=0,
        le=150,
        description="用户年龄",
    )

user = User(name="Alice", age=25)
print(user.model_dump())  # {'name': 'Alice', 'age': 25}

3. f-string

Python 3.6+ 推荐用 f-string 做字符串插值，可读性比 % 和 .format() 都好。

author = "Alice"
to = "Bob"
result = f"你好，{author}！这封邮件是发送给 {to} 的。"

4. range 与切片

lista = list(range(1, 7, 2))          # [1, 3, 5]
listb = sorted(lista, reverse=True)   # [5, 3, 1]
listb[-1]                             # 1，倒数第一个
listb[0:1]                            # [5]，切片左闭右开

5. 字典操作

字典支持解包合并（Python 3.9+）：

a = {"x": 1, "y": 2}
b = {"y": 3, "z": 4}
c = {**a, **b}  # {'x': 1, 'y': 3, 'z': 4}
del c["x"]      # 删除键

6. 函数的变长参数

def sum_all(*numbers: int) -> int:
    return sum(numbers)

def build_user(**kwargs: str) -> dict:
    return kwargs

sum_all(1, 2, 3)              # 6
build_user(name="Alice", age="25")  # {'name': 'Alice', 'age': '25'}

7. 模块引用

# ppp.py 中定义了 def abc(): ...
from ppp import abc

8. 类的构造方法

Python 不支持方法重载，多个 __init__ 会互相覆盖，只保留最后一个。

class Demo:
    def __init__(self, x):
        self.x = x

    def __init__(self, x, y):  # 上面的定义被覆盖
        self.x = x
        self.y = y

9. JSON 读写

import json

with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)

with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

10. unittest 入口

if __name__ == "__main__":
    unittest.main()

被导入时 __name__ 是模块名，只有直接执行时才等于 "__main__"。

11. matplotlib 快速绘图

import matplotlib.pyplot as plt

ss = [1, 4, 9, 16, 25, 36, 49, 64, 81, 100, 121, 144]
fig, ax = plt.subplots()
ax.plot(ss)
ax.set_title("Square Numbers")
plt.show()

12. CSV 处理

import csv

with open("data.csv", newline="", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(row["name"], row["age"])

13. 建立虚拟环境

python -m venv ll_env
source ll_env/bin/activate  # Linux/macOS
ll_env\Scripts\activate     # Windows

一、Pythonic 思维

Python 的“风格”不是语法规则，而是一种让代码更简洁、可读、可维护的思维方式。本章的建议大多不依赖某个库，而是写代码时的默认选择。

14. 检查 Python 版本

不同版本差异很大。写脚本前确认目标版本，避免用了高版本特性却跑在低版本环境。

import sys
print(sys.version_info)

15. 遵循 PEP 8 风格指南

缩进 4 个空格
行宽 79 字符（现代项目常放宽到 100 或 120）
函数名、变量名用 snake_case
类名用 CamelCase
常量用 UPPER_SNAKE_CASE

工具链：black、ruff、flake8。

16. 区分 bytes 与 str

bytes 是原始二进制数据，str 是 Unicode 文本。混用是最常见的编码 bug 来源。

b = b"hello"        # bytes
s = "hello"         # str

# 显式编解码
b.decode("utf-8")   # -> str
s.encode("utf-8")   # -> bytes

落地建议：文件读取、网络请求、数据库返回的边界处，统一做编码转换，内部逻辑全部用 str。

17. 优先使用 f-string

name = "Alice"
age = 30

# 不推荐
print("Name: %s, Age: %d" % (name, age))
print("Name: {}, Age: {}".format(name, age))

# 推荐
print(f"Name: {name}, Age: {age}")
print(f"Name: {name!r}, Age: {age:.2f}")  # !r 用 repr，:.2f 格式化数字

18. 用辅助函数替代复杂表达式

复杂表达式一行写完很爽，但调试和复用都痛苦。

# 不推荐
result = (x + y) * 2 if x > 0 and y > 0 else (x - y) * 2

# 推荐
def compute_adjustment(x: int, y: int) -> int:
    if x > 0 and y > 0:
        return (x + y) * 2
    return (x - y) * 2

result = compute_adjustment(x, y)

19. 用解包替代索引取值

pair = ("Alice", 30)

# 不推荐
name = pair[0]
age = pair[1]

# 推荐
name, age = pair

20. 用 `enumerate` 替代 `range(len(...))`

fruits = ["apple", "banana", "cherry"]

# 不推荐
for i in range(len(fruits)):
    print(i, fruits[i])

# 推荐
for i, fruit in enumerate(fruits):
    print(i, fruit)

# 还可以指定起始索引
for i, fruit in enumerate(fruits, start=1):
    print(i, fruit)

21. 用 `zip` 并行处理多个迭代器

names = ["Alice", "Bob", "Charlie"]
ages = [25, 30, 35]

for name, age in zip(names, ages):
    print(f"{name}: {age}")

当长度不一致时，zip 会以最短为准。需要补齐时用 itertools.zip_longest。

22. 避免 `for/while ... else`

else 块只在循环没有因 break 退出时执行，语义非常容易误解。

# 容易误读
for x in items:
    if x < 0:
        break
else:
    print("all positive")

# 更清晰的写法
found_negative = False
for x in items:
    if x < 0:
        found_negative = True
        break
if not found_negative:
    print("all positive")

23. 用赋值表达式减少重复

# 不推荐
count = get_count()
if count > 0:
    process(count)

# 推荐
if (count := get_count()) > 0:
    process(count)

章节小结：Pythonic 思维的核心是“可读性优先”。多利用解包、enumerate、zip、f-string、赋值表达式等语法糖，但不要把代码写成一行炫技。当表达式复杂时，果断拆成辅助函数。

二、列表和字典

列表和字典是 Python 最常用的两种数据结构。本章的建议集中在如何高效、安全、可维护地操作它们。

24. 了解序列切片

切片支持越界、负索引和省略参数。

a = [1, 2, 3, 4, 5]

a[:3]    # [1, 2, 3]
a[2:]    # [3, 4, 5]
a[::2]   # [1, 3, 5]
a[::-1]  # [5, 4, 3, 2, 1]
a[1:100] # [2, 3, 4, 5]，不报错

25. 不要在单次切片中同时指定起止和步进

# 不推荐：stride 和 start/end 同时出现，可读性差
x = a[1:-1:2]

# 推荐：拆成两步
b = a[::2]
x = b[1:-1]

26. 用星号解包捕获多个元素

first, *middle, last = [1, 2, 3, 4, 5]
# first = 1, middle = [2, 3, 4], last = 5

a, *b = [1]  # a=1, b=[]

27. 用 `sort` 的 `key` 表达复杂排序

students = [
    {"name": "Alice", "age": 20},
    {"name": "Bob", "age": 18},
    {"name": "Charlie", "age": 20},
]

# age 降序，name 升序
sorted_students = sorted(students, key=lambda x: (-x["age"], x["name"]))

28. 不要过分依赖字典的插入顺序

虽然 Python 3.7+ 保证字典插入顺序，但如果代码需要跨语言或兼容旧版本，仍应显式排序。

from collections import OrderedDict

# 当顺序是业务逻辑的一部分时，显式表达
ordered = OrderedDict([("a", 1), ("b", 2)])

29. 用 `get` 处理缺失键

# 不推荐
counts = {}
if "apple" in counts:
    counts["apple"] += 1
else:
    counts["apple"] = 1

# 推荐
counts["apple"] = counts.get("apple", 0) + 1

30. 用 `defaultdict` 替代 `setdefault`

from collections import defaultdict

# 不推荐
visits = {}
visits.setdefault("China", set()).add("Beijing")

# 推荐
visits = defaultdict(set)
visits["China"].add("Beijing")

31. 用 `missing` 构建依赖键的默认值

class MyDict(dict):
    def __missing__(self, key):
        value = self[key] = f"computed-{key}"
        return value

d = MyDict()
print(d["foo"])  # computed-foo
print(d)         # {'foo': 'computed-foo'}

章节小结：操作列表和字典时，优先使用切片、解包、get、defaultdict 等 Python 提供的简洁写法。需要表达复杂逻辑时，用 key 函数或自定义 __missing__，而不是写一堆 if key in dict。

三、函数

函数是 Python 中组织逻辑的核心单元。本章讨论如何设计清晰、健壮、易扩展的函数接口。

32. 函数返回值不要超过 3 个

返回多个未命名值会让调用端极易出错。

from typing import NamedTuple

# 不推荐
def get_user():
    return "Alice", 25, "Beijing"

name, age, city = get_user()  # 顺序一旦变化就崩

# 推荐
class User(NamedTuple):
    name: str
    age: int
    city: str

def get_user() -> User:
    return User("Alice", 25, "Beijing")

u = get_user()
print(u.name, u.age)

33. 异常优于返回 `None`

# 不推荐：None 容易与 0、False、空字符串混淆
def divide(a, b):
    if b == 0:
        return None
    return a / b

# 推荐
def divide(a, b):
    if b == 0:
        raise ValueError("b cannot be zero")
    return a / b

34. 闭包与变量作用域

闭包可以引用外层变量，但赋值时需要 nonlocal。

def make_counter():
    count = 0

    def counter():
        nonlocal count
        count += 1
        return count

    return counter

c = make_counter()
print(c())  # 1
print(c())  # 2

35. 用可变位置参数让接口更简洁

def log(message, *args):
    print(message.format(*args))

log("Hello, {}", "Alice")
log("{} + {} = {}", 1, 2, 3)

注意：不要把无限生成器用 * 展开传给函数，会耗尽内存。

36. 用关键字参数表示可选行为

def connect(host, port=3306, timeout=30):
    ...

# 调用意图清晰
connect("localhost", timeout=10)

37. 用 `None` 和 docstring 处理动态默认值

from datetime import datetime

# 错误：默认值只在定义时计算一次
def log_event(msg, when=datetime.now()):
    ...

# 正确
def log_event(msg, when=None):
    """Log a message with optional timestamp.

    Args:
        msg: Message to log.
        when: Timestamp; defaults to current time.
    """
    if when is None:
        when = datetime.now()
    print(f"{when}: {msg}")

38. 用仅限关键字和仅限位置参数增强接口清晰度

def greet(name, /, greeting="Hello", *, excited=False):
    """
    name: 只能位置传参
    greeting: 位置或关键字均可
    excited: 只能关键字传参
    """
    tail = "!" if excited else "."
    print(f"{greeting}, {name}{tail}")

greet("Alice")                      # OK
greet("Alice", "Hi")                # OK
greet("Alice", excited=True)        # OK
# greet(name="Alice")               # 错误：name 是位置-only

39. 用 `functools.wraps` 保留装饰器元信息

from functools import wraps

def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print("before")
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def add(a, b):
    """Return sum of a and b."""
    return a + b

print(add.__name__)   # add
print(add.__doc__)    # Return sum of a and b.

章节小结：设计函数接口时，优先让调用方“一看就懂”。用关键字参数、位置/关键字限定、命名元组返回值来处理可选行为和复杂返回；用 None 处理动态默认值；用 @wraps 保证装饰器透明。

四、推导与生成器

推导式和生成器是 Python 表达数据转换的利器。本章的重点是可读性边界和内存效率。

40. 用列表推导替代 `map`/`filter`

a = [1, 2, 3, 4, 5]

# 不推荐
squares = list(map(lambda x: x**2, filter(lambda x: x % 2 == 0, a)))

# 推荐
squares = [x**2 for x in a if x % 2 == 0]

41. 控制推导式的复杂度

条件、嵌套、转换超过两个子表达式时，建议改写成普通循环。

# 不推荐：难以理解
matrix = [[...]]
flat = [x for row in matrix for cell in row for x in cell if x > 0]

# 推荐
flat = []
for row in matrix:
    for cell in row:
        for x in cell:
            if x > 0:
                flat.append(x)

42. 用赋值表达式消除推导中的重复

def get_batches(count, size):
    return count // size

stocks = {"apple": 10, "banana": 3}
order = ["apple", "banana", "orange"]

found = {
    name: batches
    for name in order
    if (batches := get_batches(stocks.get(name, 0), 4))
}
# {'apple': 2}

43. 让函数用 `yield` 逐个生成值

def read_large_file(path):
    with open(path, "r") as f:
        for line in f:
            yield line.strip()

# 内存友好，每次只处理一行
for line in read_large_file("huge.log"):
    process(line)

44. 谨慎迭代函数收到的参数

迭代器只能遍历一次。

def normalize(numbers):
    total = sum(numbers)
    for n in numbers:  # 如果 numbers 是迭代器，这里已经空了
        yield 100 * n / total

it = iter([1, 2, 3])
print(list(normalize(it)))  # []

解决方案：把参数转换成列表，或要求调用方传入可重复遍历的集合。

def normalize(numbers):
    numbers = list(numbers)  # 显式物化
    total = sum(numbers)
    for n in numbers:
        yield 100 * n / total

45. 用生成器表达式改写大列表推导

# 列表推导：一次性占用大量内存
lengths = [len(x) for x in open("file.txt")]

# 生成器表达式：惰性求值
lengths = (len(x) for x in open("file.txt"))
print(next(lengths))

46. 用 `yield from` 连接多个生成器

def gen_a():
    yield 1
    yield 2

def gen_b():
    yield 3
    yield 4

def gen_all():
    yield from gen_a()
    yield from gen_b()

print(list(gen_all()))  # [1, 2, 3, 4]

47. 不要用 `send` 给生成器注入数据

send 会让 yield 表达式返回新值，但与 yield from 组合时行为复杂，团队代码里容易成为“谜之代码”。

48. 不要用 `throw` 变换生成器状态

throw 可向生成器发送异常，同样难以理解且难以调试。

49. 用 `itertools` 拼装迭代器

from itertools import chain, cycle, islice, repeat, tee

list(chain([1, 2], [3, 4]))          # [1, 2, 3, 4]
list(repeat("x", 3))                 # ['x', 'x', 'x']
list(islice(cycle([1, 2]), 5))       # [1, 2, 1, 2, 1]

it = iter([1, 2, 3])
a, b = tee(it, 2)

章节小结：推导式适合简单转换，生成器适合大数据和惰性计算。不要为了一点代码量牺牲可读性；当推导式超过两个子表达式时，改写成循环更稳妥。同时记住迭代器只能遍历一次，必要时显式物化。

五、类与接口

Python 的面向对象非常灵活，本章讨论如何用类构建清晰、可组合、可测试的设计。

50. 类使用组合，避免嵌套内置类型

复杂结构应该封装成类，而不是到处传递 dict 或 tuple。

# 不推荐
def process(data: dict):
    name = data["name"]
    address = data["address"]["city"]

# 推荐
from dataclasses import dataclass

@dataclass
class Address:
    city: str

@dataclass
class Person:
    name: str
    address: Address

def process(person: Person):
    print(person.address.city)

51. 让简单接口接受函数，而不是实例

names = ["Alice", "Bob", "Charlie"]
names.sort(key=len)  # 传入函数即可

defaultdict 的工厂函数、sorted 的 key 都是这种思想的体现。

52. 通过 `@classmethod` 多态构造对象

class InputData:
    def read(self):
        raise NotImplementedError

class PathInputData(InputData):
    def __init__(self, path):
        self.path = path

    def read(self):
        with open(self.path) as f:
            return f.read()

class Worker:
    def __init__(self, input_data):
        self.input_data = input_data

    @classmethod
    def create_workers(cls, input_class, config):
        workers = []
        for item in config:
            workers.append(cls(input_class(item)))
        return workers

53. 通过 `super()` 初始化超类

class Base:
    def __init__(self, value):
        self.value = value

class Derived(Base):
    def __init__(self, value, extra):
        super().__init__(value)
        self.extra = extra

多重继承时，super() 配合 MRO 能保证父类初始化顺序正确。

54. 用 Mixin 表示可组合的功能

class JSONSerializableMixin:
    def to_json(self):
        import json
        return json.dumps(self.__dict__)

class User(JSONSerializableMixin):
    def __init__(self, name):
        self.name = name

u = User("Alice")
print(u.to_json())  # {"name": "Alice"}

55. 优先使用 public 属性

Python 没有真正的私有。_ 开头是约定上的 protected，__ 开头只是名字改写（name mangling），仍然可以访问。

class Demo:
    def __init__(self):
        self._internal = 1
        self.__mangled = 2

d = Demo()
print(d._internal)       # 可以访问
print(d._Demo__mangled)  # 也可以访问

落地建议：与其强行私有，不如把内部状态用 _ 标记，文档中说明不稳定的 API。

56. 自定义容器类继承 `collections.abc`

from collections.abc import Sequence

class MyList(Sequence):
    def __init__(self, items):
        self._items = list(items)

    def __getitem__(self, index):
        return self._items[index]

    def __len__(self):
        return len(self._items)

继承 collections.abc 的抽象基类可以自动帮你补齐 __iter__、__contains__ 等方法。

章节小结：类的设计原则是“组合优于嵌套、接口优于实现”。用 @dataclass 做数据封装，用 @classmethod 做多态构造，用 Mixin 组合横切功能，用 collections.abc 保证容器接口完整。

六、元类与属性

本章进入 Python 的动态特性：属性访问控制、描述符、元类与类装饰器。这些特性威力大，但也容易过度使用。

57. 用 `@property` 取代 getter/setter

class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("Too cold")
        self._celsius = value

58. 不要急着用 `@property` 重构旧代码

只有当访问逻辑变得复杂、且多处重复时，才值得引入 @property。简单字段直接公开即可。

59. 用描述符改写需要复用的 property

class Validated:
    def __set_name__(self, owner, name):
        self.name = name
        self.private_name = f"_{name}"

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, self.private_name, None)

    def __set__(self, obj, value):
        self.validate(value)
        setattr(obj, self.private_name, value)

    def validate(self, value):
        raise NotImplementedError

class NonNegative(Validated):
    def validate(self, value):
        if value < 0:
            raise ValueError(f"{self.name} must be >= 0")

class Person:
    age = NonNegative()

p = Person()
p.age = 30
# p.age = -1  # ValueError

60. 针对惰性属性使用 `getattr`、`getattribute`、`setattr`

class LazyRecord:
    def __init__(self):
        self.exists = 5

    def __getattr__(self, name):
        value = f"Value for {name}"
        setattr(self, name, value)
        return value

data = LazyRecord()
print(data.exists)    # 5，普通属性
print(data.foo)       # Value for foo，触发 __getattr__
print(data.foo)       # Value for foo，已缓存

61. 用 `__init_subclass__` 验证子类

class Base:
    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        if not hasattr(cls, "required_method"):
            raise TypeError(f"{cls.__name__} must define required_method")

class Good(Base):
    def required_method(self):
        pass

# class Bad(Base): pass  # TypeError

62. 用 `__init_subclass__` 记录子类

class PluginBase:
    plugins = []

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.plugins.append(cls)

class PluginA(PluginBase):
    pass

class PluginB(PluginBase):
    pass

print(PluginBase.plugins)  # [<class PluginA>, <class PluginB>]

63. 用 `__set_name__` 给类属性加注解

如第 59 条示例，__set_name__ 让描述符在类创建时自动拿到属性名。

64. 优先考虑类装饰器，而不是元类

类装饰器通常比元类更易读、更易调试。

def add_repr(cls):
    def __repr__(self):
        attrs = ", ".join(f"{k}={v!r}" for k, v in self.__dict__.items())
        return f"{cls.__name__}({attrs})"
    cls.__repr__ = __repr__
    return cls

@add_repr
class Person:
    def __init__(self, name):
        self.name = name

p = Person("Alice")
print(p)  # Person(name='Alice')

章节小结：属性访问控制、描述符、类装饰器、元类都是 Python 提供的元编程工具。日常开发中，@property 和类装饰器已经能解决 90% 的问题；描述符和元类适合框架级代码，业务代码里应谨慎使用。

七、并发与并行

Python 的并发模型有三条路：多线程、多进程、协程。本章的核心是根据场景选对工具。

65. subprocess 管理子进程

import subprocess

# 同步等待
result = subprocess.run(["ls", "-l"], capture_output=True, text=True)
print(result.stdout)

# 异步启动
proc = subprocess.Popen(["sleep", "5"])
print("doing other things...")
proc.communicate()  # 等待完成

66. 不要用线程做 CPU 密集型并行计算

GIL 限制了同一时刻只有一个线程执行 Python 字节码。多线程适合 I/O 等待，不适合纯计算。

import threading

# 这个例子不会因为多线程而加速
def count(n):
    while n > 0:
        n -= 1

threads = [threading.Thread(target=count, args=(100_000_000,)) for _ in range(2)]
for t in threads:
    t.start()
for t in threads:
    t.join()

67. 用 `Lock` 防止多线程竞争

from threading import Lock, Thread

counter = 0
lock = Lock()

def increment():
    global counter
    for _ in range(100_000):
        with lock:
            counter += 1

threads = [Thread(target=increment) for _ in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

print(counter)  # 1_000_000

68. 用 `Queue` 协调线程进度

from queue import Queue
from threading import Thread

q = Queue(maxsize=1)  # 容量为 1，形成背压

def producer():
    for i in range(5):
        q.put(i)
        print(f"produced {i}")
    q.put(None)  # 结束信号

def consumer():
    while True:
        item = q.get()
        if item is None:
            break
        print(f"consumed {item}")

Thread(target=producer).start()
Thread(target=consumer).start()

69. 用 `ThreadPoolExecutor` 做线程池

from concurrent.futures import ThreadPoolExecutor, as_completed

def fetch(url):
    import urllib.request
    with urllib.request.urlopen(url, timeout=5) as resp:
        return len(resp.read())

urls = ["https://example.com"] * 5
with ThreadPoolExecutor(max_workers=4) as executor:
    futures = {executor.submit(fetch, url): url for url in urls}
    for future in as_completed(futures):
        print(future.result())

70. 协程实现高并发 I/O

import asyncio

async def say_after(delay, what):
    await asyncio.sleep(delay)
    print(what)

async def main():
    await asyncio.gather(
        say_after(1, "hello"),
        say_after(2, "world"),
    )

asyncio.run(main())

71. `asyncio.run_in_executor` 包裹同步阻塞调用

import asyncio
from concurrent.futures import ThreadPoolExecutor

def blocking_io():
    import time
    time.sleep(1)
    return "done"

async def main():
    loop = asyncio.get_running_loop()
    with ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, blocking_io)
        print(result)

asyncio.run(main())

72. 用 `concurrent.futures` 实现多进程

from concurrent.futures import ProcessPoolExecutor

def fib(n):
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

with ProcessPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(fib, [30, 31, 32, 33]))
    print(results)

章节小结：并发工具选择的核心是 GIL。I/O 密集型优先协程，次选线程；CPU 密集型用多进程。线程间共享状态要加锁，协程里不要阻塞事件循环，必要时用 run_in_executor。

八、稳定与性能

本章关注如何让程序更可靠、更可预测、更快。但前提永远是：先分析，再优化。

73. 合理利用 `try/except/else/finally`

def read_file(path):
    f = open(path, "r")
    try:
        data = f.read()
    except UnicodeDecodeError as e:
        print(f"decode error: {e}")
        raise
    else:
        print(f"read {len(data)} bytes")
        return data
    finally:
        f.close()

74. 用 `contextlib` 和 `with` 改写复用 `try/finally`

from contextlib import contextmanager

@contextmanager
def managed_resource(name):
    print(f"acquiring {name}")
    yield name
    print(f"releasing {name}")

with managed_resource("db") as r:
    print(f"using {r}")

75. 用 `datetime` 处理本地时间

from datetime import datetime, timezone

# 不推荐：依赖系统时区的 naive datetime
now = datetime.now()

# 推荐：显式带时区
utc_now = datetime.now(timezone.utc)
print(utc_now)

76. 用 `copyreg` 实现可靠的 pickle 操作

import copyreg
import pickle

class GameState:
    def __init__(self, level, health):
        self.level = level
        self.health = health

def pickle_game_state(state):
    kwargs = {"level": state.level, "health": state.health}
    return unpickle_game_state, (kwargs,)

def unpickle_game_state(kwargs):
    return GameState(**kwargs)

copyreg.pickle(GameState, pickle_game_state)

state = GameState(1, 100)
data = pickle.dumps(state)
restored = pickle.loads(data)

77. 用 `Decimal` 做精确计算

from decimal import Decimal, ROUND_HALF_UP

# 浮点数的精度问题
print(0.1 + 0.2)  # 0.30000000000000004

# Decimal 精确控制
price = Decimal("0.1") + Decimal("0.2")
print(price)  # 0.3

# 控制舍入
fee = Decimal("10.005").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
print(fee)  # 10.01

78. 先分析性能，再优化

python -m cProfile -s cumtime my_script.py

不要凭感觉优化。用 cProfile 找到真正的热点函数。

79. 优先考虑 `deque` 实现生产者-消费者队列

from collections import deque

d = deque()
d.append(1)
d.appendleft(0)
d.pop()       # 1
d.popleft()   # 0

deque 两端操作都是 O(1)，list 的 pop(0) 是 O(n)。

80. 用 `bisect` 搜索已排序序列

import bisect

values = [1, 3, 5, 7, 9]
index = bisect.bisect_left(values, 4)
print(index)  # 2，4 应该插入的位置

81. 用 `heapq` 制作优先级队列

import heapq
from functools import total_ordering

@total_ordering
class Task:
    def __init__(self, priority, name):
        self.priority = priority
        self.name = name

    def __lt__(self, other):
        return self.priority < other.priority

    def __eq__(self, other):
        return self.priority == other.priority

heap = []
heapq.heappush(heap, Task(2, "write tests"))
heapq.heappush(heap, Task(1, "fix bug"))

while heap:
    task = heapq.heappop(heap)
    print(task.priority, task.name)

82. 用 `memoryview` 与 `bytearray` 实现零拷贝 bytes 操作

data = bytearray(b"hello world")
mv = memoryview(data)
sub = mv[6:11]
sub[0] = ord("W")  # 修改会影响原始 data
print(data)  # bytearray(b'hello World')

章节小结：稳定性的关键是边界处理和资源管理，性能的关键是选对数据结构和避免过早优化。Decimal 处理钱、deque 处理队列、bisect/heapq 处理有序和优先数据、cProfile 指导优化方向。

九、测试与调试

测试不是写完代码后的“补充工作”，而是代码的一部分。本章讨论如何写出可维护、可定位问题的测试与调试策略。

83. 通过 `repr` 字符串输出调试信息

x = {"a": 1, "b": [2, 3]}
print(repr(x))  # {'a': 1, 'b': [2, 3]}

# 自定义类也应实现 __repr__
class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point({self.x!r}, {self.y!r})"

p = Point(1, 2)
print(repr(p))  # Point(1, 2)

84. 在 `TestCase` 子类里验证相关行为

import unittest

class TestStringMethods(unittest.TestCase):
    def test_upper(self):
        self.assertEqual("foo".upper(), "FOO")

    def test_isupper(self):
        self.assertTrue("FOO".isupper())
        self.assertFalse("Foo".isupper())

if __name__ == "__main__":
    unittest.main()

85. 测试前后准备与清理放在 `setUp`/`tearDown`

class TestDatabase(unittest.TestCase):
    def setUp(self):
        self.conn = create_test_db()

    def tearDown(self):
        self.conn.close()
        cleanup_test_db()

    def test_insert(self):
        self.conn.execute("INSERT INTO users VALUES ('Alice')")
        row = self.conn.execute("SELECT * FROM users").fetchone()
        self.assertEqual(row[0], "Alice")

86. 用 `Mock` 模拟复杂依赖

from unittest.mock import Mock, patch

def get_user_name(user_id):
    import requests
    resp = requests.get(f"/users/{user_id}")
    return resp.json()["name"]

with patch("requests.get") as mock_get:
    mock_get.return_value.json.return_value = {"name": "Alice"}
    assert get_user_name(1) == "Alice"

87. 把依赖系统封装起来，便于模拟和测试

from abc import ABC, abstractmethod

class UserRepository(ABC):
    @abstractmethod
    def get(self, user_id):
        ...

class HttpUserRepository(UserRepository):
    def get(self, user_id):
        ...  # 真实 HTTP 调用

class FakeUserRepository(UserRepository):
    def __init__(self, users):
        self.users = users

    def get(self, user_id):
        return self.users.get(user_id)

# 测试时使用 FakeUserRepository

88. 考虑用 `pdb` 做交互调试

def buggy_func(x):
    import pdb; pdb.set_trace()
    return x / 0

buggy_func(10)

常用命令：n（下一步）、s（进入函数）、c（继续）、p var（打印变量）、q（退出）。

89. 用 `tracemalloc` 掌握内存使用与泄漏

import tracemalloc

tracemalloc.start()

# 运行你的代码
large = [bytearray(1024 * 1024) for _ in range(100)]

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics("lineno")[:10]
for stat in top_stats:
    print(stat)

章节小结：好的测试应贴近真实使用场景，同时把外部依赖隔离。用 setUp/tearDown 管理状态，用抽象接口和 Mock 隔离外部系统，用 pdb 和 tracemalloc 定位 bug 和内存问题。

十、协作开发

代码最终要被人读、被人改。本章的建议关乎如何让代码在团队中稳定地演进。

90. 学会寻找社区模块

遇到通用问题先查 PyPI：https://pypi.org。不要重复造轮子，但也不要盲目引入依赖。

91. 用虚拟环境隔离项目，并重建依赖关系

# 生成依赖
pip freeze > requirements.txt

# 重建环境
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

生产环境建议用 pip-tools 或 poetry 管理依赖树。

92. 每个函数、类与模块都要写 docstring

def calculate_area(radius):
    """Calculate the area of a circle.

    Args:
        radius: The radius of the circle.

    Returns:
        The area as a float.

    Raises:
        ValueError: If radius is negative.
    """
    if radius < 0:
        raise ValueError("radius must be non-negative")
    return 3.14159 * radius ** 2

93. 用包来安排模块，提供稳固 API

myproject/
    __init__.py
    core.py
    utils.py

# __init__.py
from .core import process
from .utils import helper

__all__ = ["process", "helper"]

94. 用模块级代码配置不同部署环境

import os

ENV = os.getenv("APP_ENV", "development")

if ENV == "production":
    DATABASE_URL = os.getenv("DATABASE_URL")
else:
    DATABASE_URL = "sqlite:///dev.db"

95. 为自编模块定义根异常

class MyLibError(Exception):
    """Base exception for mylib."""

class ConfigError(MyLibError):
    """Raised when configuration is invalid."""

# 调用方可以统一捕获 MyLibError
try:
    do_something()
except MyLibError as e:
    logger.error(f"mylib error: {e}")

96. 用适当方式打破循环依赖

最佳方案是把公共代码下沉到依赖最底层：

# 不推荐：A -> B -> A

# 推荐：A -> common <- B

如果重构成本高，可以用动态导入：

def do_something():
    from module_b import helper
    helper()

97. 重构时用 `warnings` 提醒 API 变更

import warnings

def old_function():
    warnings.warn(
        "old_function is deprecated, use new_function instead",
        DeprecationWarning,
        stacklevel=2,
    )
    return new_function()

98. 考虑用 `typing` 做静态分析

from typing import Optional, List

def find_user(user_id: int) -> Optional[dict]:
    ...

def list_users(ids: List[int]) -> List[dict]:
    ...

配合 mypy、pyright 等类型检查工具，能在运行前发现一类常见 bug。

章节小结：协作开发的核心是“让别人能安全地改你的代码”。用虚拟环境隔离依赖、用 docstring 和类型注解降低理解成本、用根异常和 warnings 提供稳定的 API 演进路径、用包结构控制对外暴露的接口。

全文总结

《Effective Python》的 90 条建议并不是孤立的技巧，而是一套从代码风格到系统设计的完整思维框架。通读下来，可以提炼出几条贯穿全书的主线：

可读性优先。Python 的设计哲学是“有一种明显的方式去做一件事”。f-string、解包、enumerate、zip、with、列表推导等语法特性，都是为了让意图更直接。不要为了少写几行而牺牲可读性。
显式优于隐式。无论是时区、编码、动态默认值，还是循环依赖、API 废弃，都应该在代码中明确表达，而不是依赖隐式行为或口头约定。
根据场景选择工具。并发选线程、协程还是进程？排序用 sort、二分还是堆？精度用 float 还是 Decimal？没有银弹，只有合适的工具。
测试和文档是代码的一部分。Mock、抽象接口、docstring、类型注解、warnings，都是为了让代码在团队中可持续演进。
先分析，再优化。性能问题要用 cProfile 验证，内存问题要用 tracemalloc 观察，避免凭感觉做“优化”。

最后，这些建议的价值不在于一次性背下来，而在于形成写代码时的默认习惯。每次写完一段代码，都可以回头问一句：这里有没有更 Pythonic、更可维护、更高效的写法？坚持这个习惯，90 条建议自然会内化为直觉。

我在 ftmao.com/blog 持续输出 AI 工程、Python 实践与多模态生成相关内容，欢迎关注和交流。

Python on 方糖猫Blog

Spring Boot + Python 双栈架构：AI 服务的工程化实践

Spring Boot + Python 双栈架构：AI 服务的工程化实践

一、为什么必须双栈？

二、整体架构

三、职责划分

3.1 Java 侧职责

3.2 Python 侧职责

3.3 边界原则

四、服务间通信

4.1 异步通信：RocketMQ

4.2 同步通信：HTTP / gRPC

4.3 数据一致性

五、数据库设计

5.1 按服务分库还是分表？

5.2 Python 侧如何访问数据库

六、部署与运维

6.1 容器化

6.2 CI/CD

6.3 日志与链路追踪

6.4 监控告警

七、踩过的坑

7.1 序列化不一致

7.2 Python 服务内存泄漏

7.3 跨语言异常处理

7.4 开发环境复杂度

八、双栈架构的收益与代价

8.1 收益

8.2 代价

九、什么情况下不要双栈？

十、总结

LangGraph 入门：给传统工程师的 Agent 状态与编排指南

LangGraph 入门：给传统工程师的 Agent 状态与编排指南

一、LangGraph 是什么？

二、State：Agent 的"工作记忆"

一个简单的 State 定义

为什么 State 如此重要？

三、任务编排：图、节点、边

一个简化版的视频生成图

条件边的价值

四、长期记忆：从单线程到跨会话

Checkpointer：线程级的"短期记忆"

Store：真正的长期记忆

在项目中怎么落地？

五、实战小技巧

1. 用图片/Mermaid 输出流程图

2. 打印提示词调试

3. 把节点拆小，便于追踪

4. 用 State 的字段做日志锚点

5. 不要忽视错误分支

六、LangGraph 适合什么场景？

七、总结

LangChain 入门笔记：AI 视频生成实战

LangChain 入门笔记：AI 视频生成实战

一、LangChain 解决什么问题？

二、课程核心内容回顾

三、核心组件原理与示例

3.1 Models & Prompts：统一接口与模板复用

3.2 Output Parsers：从文本到结构化数据

3.3 Memory：多轮修改不再"失忆”

3.4 Chains：把多个步骤串成流水线

3.5 RAG：用本地素材库增强脚本生成

3.6 Agents：让 LLM 自己决定下一步

四、Demo：一个可扩展的"AI 视频脚本生成器"

五、分布式场景下的运行方案

推荐架构

关键设计点

六、服务器异常恢复方案

1. 分级重试策略

2. 幂等性设计

3. 死信队列（DLQ）

4. 状态快照与断点续跑

七、如何实现高并发

1. 异步调用释放线程

2. 流式响应降低首字节延迟

3. 限流与背压

4. 缓存常用结果

5. 水平扩展与资源隔离

八、学完这门课的几点体会

九、参考资源

20. 用 `enumerate` 替代 `range(len(...))`

21. 用 `zip` 并行处理多个迭代器

22. 避免 `for/while ... else`

27. 用 `sort` 的 `key` 表达复杂排序

29. 用 `get` 处理缺失键

30. 用 `defaultdict` 替代 `setdefault`