黑马程序员 Agent 教学项目 Demo改编版

当前版本基线

LangChain 的各个 Python 包独立发版，版本号并不相同。本项目的锁文件使用截至 2026-08-18 的当前最新版：

组件	锁定版本
langchain	1.3.15
langchain-core	1.5.6
langchain-ollama	1.1.0
langchain-chroma	1.1.0
langchain-text-splitters	1.1.2
langgraph	1.2.11

uv.lock 则保证教学和测试环境可复现。

uv lock --upgrade
uv sync --group dev
uv run pytest

主要升级内容

• 使用当前 LangChain 1.x 的 create_agent、Agent State 和 Event Streaming v3。Event Streaming v3 是官方当前推荐的新流式接口，但在当前底层实现中仍标记为 beta。
• fill_context_for_report 触发后，由中间件通过 Command 更新 report_mode 状态；不再修改用于静态依赖注入的 Runtime context。
• 聊天模型与向量模型改用 langchain-ollama，均在本地运行，不需要百炼 API Key，也不产生云端接口费用。
• PDF 直接由 pypdf 读取，再转换为 LangChain Document。
• Chroma 数据库和已索引文件记录统一放在 .runtime/，并使用项目绝对路径，不受启动目录影响。
• 模型、向量库和 RAG 服务延迟初始化；页面启动时不会立即加载数 GB 的本地模型。
• Streamlit 使用 st.write_stream 的返回值保存完整回答，并把历史消息传回 Agent。

模型选择

我的笔记本是 Apple M5、8 核 GPU、16GB 统一内存的 MacBook Air。模型权重、KV Cache、Ollama 运行时、macOS 和其他应用会共用这 16GB，所以 Ollama 标签页的文件大小只是判断上限的第一步。

模型	Ollama 下载大小	在本机上的建议
qwen3.5:4b	3.4GB	轻快，适合学习和快速调试
qwen3.5:9b	6.6GB	默认推荐，质量与速度较均衡
qwen3:14b	9.3GB	能运行，但内存较紧、速度较慢，建议关闭其他大应用并使用 4K–8K 上下文
qwen3:30b	19GB	不建议，权重文件已超过本机统一内存
qwen3-embedding:0.6b	639MB	推荐作为本地 RAG 向量模型

运行

推荐使用 uv：

ollama pull qwen3.5:9b
ollama pull qwen3-embedding:0.6b

uv sync --group dev
cp .env.example .env

这两个 ollama pull 共需下载约 7.2GB。项目已配置好模型名，.env 只用于覆盖默认值，不需要 API Key。可先用 ollama list 确认模型已安装。

首次运行先在本地建立知识库：

uv run python index_knowledge.py

启动页面：

uv run streamlit run app.py

运行离线测试：

uv run pytest

如果更换了 Embedding 模型，应删除 .runtime/chroma_db 和 .runtime/indexed_files.json 后重新建库；不同向量模型生成的向量空间不能混用。

教学用模拟行为

以下行为是课程刻意简化的演示

• get_weather 返回固定的晴天、26 摄氏度等数据。
• get_user_location、get_user_id、get_current_month 从课程样例集合随机取值。
• fetch_external_data 读取本地 CSV，模拟外部业务系统。

当前接口依据

• LangChain Agents
• LangChain 自定义中间件与状态更新
• LangChain Event Streaming
• LangChain ChatOllama 集成
• Ollama Qwen3.5 模型标签
• Ollama Qwen3 模型标签
• Ollama Qwen3 Embedding 0.6B
• 黑马程序员大模型RAG与Agent智能体项目实战教程