LangChain on Chang Luo

在树莓派上搭建家用 Agent 服务

Sun, 18 Jan 2026 00:00:00 +0000

使用树莓派搭建 dive-into-langgraph/app 服务，在家庭局域网内部使用。

一键部署脚本：agent-server

一、制作 TF 卡

Note: 你可以参考我的这篇博客《树莓派 5 装机指南》，它写得更详细一些。但部分信息已经过时，请注意甄别。

1）下载

你需要下载两样东西：

Raspberry Pi Imager：将镜像写入 TF 卡的工具
Ubuntu 24.04.3 LTS：树莓派的 Ubuntu 镜像

Ubuntu 镜像有两种版本：桌面版、服务器版，我们下载服务器版。下载的时候可以检查一下，安装包的文件名应该是这个 ubuntu-24.04.3-preinstalled-server-arm64+raspi.img.xz

2）将镜像写入 TF 卡

根据 Raspberry Pi Imager 的指引，完成镜像烧录的过程就好了。并没有什么难的。唯一需要注意的是，由于我们已经下载了 Ubuntu 镜像，所以这里要选「使用自定义镜像」。

二、首次启动 Ubuntu

烧录完成后，按以下步骤操作：

先断电，然后将 TF 卡插入板子
连接外接显示屏、键盘、网线
最后插入电源

一般来讲，插电即可点亮。这时回车一下，即可输入账号密码，初始账密是：


账号	ubuntu
密码	ubuntu

输完账密，它会接着让你设置新密码。这里流程设计得有点人机，需要注意看提示，不然容易卡关。温馨提示：你输入 ubuntu 的次数比你想象中更多。

三、环境配置

1）更新软件包

# 更新软件源的索引列表
sudo apt update

# 根据更新后的索引，升级所有可更新的软件包
sudo apt upgrade -y

2）安装 pipx 和 uv

先安装 pipx，再用它安装 uv：

RAG：大模型时代的搜索基座

Sat, 27 Dec 2025 00:00:00 +0000

没有一条帆船能吹动自己行驶，它需要外面的风。 – 因可觅《量子离歌》

大模型的训练数据有截止日期，在此之后的事它不知道；大模型的参数量有限，无法容纳所有专业知识。也就是说，大模型在实时性和专业性上都有所欠缺。

如何让大模型变得实时且专业呢？最省力的方法是“打小抄”。知识库 就像大模型的“小抄”。在回答问题之前，先瞅一眼小抄，看有没有与问题相关的内容。如果有，就从知识库中取回这段内容，结合大模型的推理能力，生成最终答案。

这里「打小抄」的动作，就是 RAG（Retrieval-Augmented Generation, 检索增强生成）。

Note: 使用知识库可以让大模型的回答有据可依、减少幻觉，代价是需要承担知识库的构建成本。尤其当知识库的规模较大时，有必要想想是否值得支付对价。毕竟，通过扩大知识库的方式提升 Agent 性能，多少有点「用有限对抗无限，用确定对抗不确定」的意思。虽然我们总是在提起 RAG 时提到知识库，但 RAG 是一种检索技术，它可以检索任何内容。比起检索需要手动构建的知识库，用来检索联网内容、历史对话也是可以的，而且性价比很高。你的下一个检索对象，又何必是知识库。

一、提示词模板

RAG 做的事情并不复杂，就是从知识库中召回与用户问题有关的内容，作为上下文注入到 提示词模板 (Prompt Template) 中。

下面是一个提示词模板：

{context}

---

基于上面给出的上下文，回答问题。

问题：{question}

回答：

使用该模板时，将召回文本填入 {context}，将用户问题填入 {question}。然后把填好的提示词模板交给大模型推理。

RAG 主要做了两件事：一是从知识库中召回与用户问题有关的文本，二是使用提示词模板拼接召回文本与用户问题。拼接很容易做到，难度主要集中在召回上。在下一小节中，我将介绍如何召回与用户问题有关的文本。

二、向量检索

完成「召回与用户问题有关的」这件事，需要用到检索器。实现检索器的方式有很多，比如基于关键词检索的 BM25 算法，但本节主要介绍基于 Embedding 的检索方法：向量检索。

1）从文本向量化说起

Embedding 是一种将文本转为向量的技术。它的输入是一段文本，输出是一个定长的向量。

"好喜欢你" --> [0.190012, 0.123555, .... ]

将文本转为向量的目的，是把语义相近的词分配到同一片向量空间。所以，一对近义词转成向量后，它们的向量之间的距离通常比其他词更近。比如，足球和篮球在向量空间中的距离更近一些，而足球和篮筐之间的距离更远。Embedding 的本质是压缩。从编码角度讲，自然语言存在冗余信息。Embedding 相当于对自然语言进行重编码，用最少的 token 表达最多的语义。

Embedding 在多语言场景下也有优势。经过充分训练的 Embedding 模型，会将多语言内容在语义层面上对齐。也就是说，一个向量可以在多语言环境中保持同一语义。这种特性让大模型得以兼容并包。即使加入多语言材料，也不会因为字面上的词不同，而产生“理解”上的混乱。

2）向量检索的原理

由于 Embedding 模型具有将相似语义的词训练成距离相近的向量的特性，我们可以把「用户问题」与「知识库内容」都转成 Embedding 向量。然后计算向量之间的距离。向量之间的距离越小，则语料之间的相似度越高。借助这个原理，最后返回知识库中与问题向量距离最小的 Top-K 份语料即可。

《LangGraph 1.0 完全指南》发布

Sun, 23 Nov 2025 00:00:00 +0000

经过三个星期的努力，《LangGraph 1.0 完全指南》终于面世啦！

10 月中旬，LangGraph 1.0 发布。开发团队承诺这是一个稳定版本，未来不会大改。因此，现在正是学习它的好时候。

LangGraph 是由 LangChain 团队开发的开源智能体框架。使用时它俩是紧密耦合的：LangChain 提供底层功能，LangGraph 负责状态管理。因此，两个库的文档都需要学习，这无疑加重了使用者的负担。为了让大家快速入门，我将两个库的主要功能提取出来，分成 14 个章节进行介绍。

这是一个开源电子书项目，使用 GitHub Action 自动构建，欢迎 Pull Request。如果你觉得本教程对你有帮助，也欢迎 Star 本教程仓库 luochang212/dive-into-langgraph。

一、在线资源

可以通过以下链接，访问本项目的仓库和在线文档：

资源	链接
GitHub 仓库	luochang212/dive-into-langgraph
电子书	《LangGraph 1.0 完全指南》

二、章节介绍

本教程的内容速览：

序号	章节	主要内容
1	快速入门	创建你的第一个 ReAct Agent
2	状态图	使用 StateGraph 创建工作流
3	中间件	使用自定义中间件实现四个功能：预算控制、消息截断、敏感词过滤、PII 检测
4	人机交互	使用内置的 HITL 中间件实现人机交互
5	记忆	创建短期记忆、长期记忆
6	上下文工程	使用 State、Store、Runtime 管理上下文
7	MCP Server	创建 MCP Server 并接入 LangGraph
8	监督者模式	两种方法实现监督者模式：tool-calling、langgraph-supervisor
9	并行	如何实现并发：节点并发、`@task` 装饰器、Map-reduce、Sub-graphs
10	RAG	三种方式实现 RAG：向量检索、关键词检索、混合检索
11	网络搜索	实现联网搜索：DashScope、Tavily 和 DDGS
12	Deep Agents	简单介绍 Deep Agents
13	Gradio APP	基于 Gradio 开发流式对话智能体应用
14	附录：调试页面	介绍 langgraph-cli 提供的调试页面

三、拓展阅读

以下是推荐阅读的文档和教程：