跳到主要内容

从笔记本到生产 — 部署、平台与安全

这一章讲三件事: 一个 RAG 应用要真正上线,需要补齐哪三块外部基础设施; 托管平台把第 5、9 章那些本地概念(状态、线程、中断、并发)升格成了哪几个 API 模型; 以及放开给真实用户前后,安全清单上必须有哪些条目。 读完你会明白:「能演示」和「能上线」之间隔着的三件事,全都跟规模和信任有关。

1. 先看现象:localhost 上的应用不叫应用​

前十章的一切都在你的笔记本上发生:模型调用、向量库(docker 里的 Postgres)、 内存里的 checkpointer。要让外部用户访问,三件事立刻缺位:

缺什么书中的选型
一个公网可达的向量库Supabase(托管的 Postgres,开 pgvector 扩展)
一个跑图、扛并发、能断点恢复的运行时LangGraph Platform(官方托管服务)
调试、监控、部署的统一观测面LangSmith(平台就集成在它的界面里)

书里的示例项目 fork 自官方 retrieval agent 模板,环境变量(存在终端里、供程序读取的配置项)一栏全列了出来—— 值得注意的有两行:

LANGCHAIN_TRACING_V2=true   # 打开轨迹上报
LANGCHAIN_ENDPOINT=…        # 上报地址(LangSmith)

只要这两行在,全链路的执行轨迹就自动上报 LangSmith,零代码改动1。 这个「免费拿到可观测性」的特性要到第 11 章才完全兑现,先记住开关在哪。

2. 顶层全景​

   用户 ──▶ LangGraph Platform(跑你的图)
                │ 读写向量 ──────▶ Supabase / pgvector
                │ 每步存档 ──────▶ 托管 Postgres checkpointer
                │ 轨迹/指标 ─────▶ LangSmith(部署入口也在这)
   图说:三个外部件各管一摊;你的代码只负责把图交给 Platform。

3. 核心原理​

3.1 向量库落地:一张表加一个函数​

Supabase 侧的搭建是三句 SQL 的功夫:启用 pgvector;建 documents 表 (content 存正文、metadata 存 jsonb、embedding 存 vector(1536)—— 数串长度按你选的嵌入模型定,1536 是书中模型的标准输出)2; 再建一个检索函数 match_documents3,它浓缩了上一章相似度搜索的全部语义:

select ...,
  1 - (documents.embedding <=> query_embedding) as similarity
from documents
where metadata @> filter          -- 先按元数据过滤(JSON 包含判断)
order by documents.embedding <=> query_embedding   -- 按向量距离升序
limit match_count;                -- 只取前 N 个

<=> 是 pgvector 的余弦距离算符(距离越小越像,所以用 1 减去它转成相似度分); @> 是 JSON 包含符,负责「只看 2023 年的文档」这类精确过滤—— 上一章 SelfQueryRetriever 生成的过滤器,落地时就翻译成这种表达式。 之后 Python 侧一行 SupabaseVectorStore(..., query_name="match_documents") 就把查询挂到了这个函数上4。

3.2 LangGraph Platform:把第 5 章的本地概念升格成 API​

本地版本的 LangGraph 是「图运行时」;Platform 是「图运行时 + 队列 + 存档 + 控制面」的托管组合。 书里给出的扩容理由很具体:agent 的负载天然不均,某几类任务会把系统压垮, Platform 负责横向扩缩任务队列与服务器(替你把图跑起来的那批机器),并配一个健壮的托管 Postgres checkpointer ——第 5 章那颗 MemorySaver 的生产形态5。

理解它的 API 只需要四个数据模型6:

模型是什么与本地概念的对应
Assistant一张编译图的配置化实例;同一张图可派生多个不同配置的 assistant「认知架构本身」被产品化了
Thread一组 run 的状态容器;想持久化就必须先建 threadthread_id 的对象化
Runassistant 的一次调用,自带输入/配置/元数据,可选挂在某个 thread 上graph.invoke(...)
Cron时刻表 + assistant + 输入;每次到点开新 thread 投递第 12 章环境计算 agent 的基础设施

某时点的 thread 状态有个正式名字:checkpoint7——第 9 章 HITL 的「从断点继续」 在平台语境里就是对 checkpoint 的操作。

功能面五项8:

  • 流式(平台级五模式:values/messages/updates/events/debug——其中 messages 模式专为聊天应用设计,要求图里真有 messages 键);

  • HITL(平台明确建议在「调工具、碰敏感文档」两类检查点(即前述 checkpoint:某一时刻的完整现场)插人工审批);

  • double texting(第 9 章五策略中的四种直接做成配置:reject/enqueue/interrupt/rollback);

  • stateless runs(免建 thread、跳过存档、用后即焚的一次性执行);

  • webhooks(run 一完成就回调——即主动发一个网络请求——给你的业务系统)9。 一处细节区分了重试语义:stateless run 重试时保留记忆,而后台任务的 worker 中途阵亡 则整个从头重跑10。

3.3 部署流程:一个配置文件,一次授权​

本地先验货:langgraph dev 起一个带热重载的本地 API(默认 2024 端口, /docs 直接给你接口文档),可以用 curl 打,也可以用 SDK(封装好的开发工具包)建线程、流式收块11。

项目里唯一的新增物是一个 langgraph.json12:

{ "dependencies": ["./my_agent"],
  "graphs": { "agent": "./my_agent/agent.py:graph" },
  "env": ".env" }

graphs 一栏把图 ID 对应到「编译好的图或造图函数」;配套的目录结构 (utils/ 里 tools/nodes/state 分文件、agent.py 造图)就是官方模板的形状13。

真部署从 LangSmith 界面走:GitHub OAuth(用 GitHub 账号登录并点一次授权的标准流程)→ 选仓库与 langgraph.json 路径 → 选分支 → 环境变量(敏感值勾 Secret)→ 提交出第一个 revision14。 书里给出的产能口径:选 Production 档,最高 500 请求/秒,高可用存储加自动备份15。 更新靠「New Revision」按钮,仪表盘上有 trace 数量图(成功/进行中/出错三色曲线)16。

LangGraph Studio 单独值得一提:它是 agent 专用的可视化 IDE, 最独特的卖点是把 agent 的执行轨迹从中途拎出来改——改结果、改某个节点的逻辑, 然后从那个时点继续,「交互式地操纵当时的状态」17。 这是第 9 章 fork(回放历史现场)的产品化形态。

3.4 安全:三条原则,三类靶场​

平台的便利把应用送到了真实用户面前,攻击面同步打开。书里的安全部分先给三原则18:

  1. 最小权限:按需授权;只读凭据、禁触敏感数据、容器隔离(行话叫沙箱(sandbox):关在受限小环境里跑);
  2. 预设滥用:假设凭据被允许的任何用法都会被用到——一对能删库的凭据, 就该当它会被要求删库;
  3. 纵深防御:多层叠加(只读+沙箱),任何单层都不当防线。

三条原则落到三个典型靶场19:

靶场攻击剧本缓解
文件系统「帮我把 X 目录里的文件删了/读一下工资表」锁目录白名单 + 只读/白名单写 + 容器
外部 API让有写权限的 API key 造脏数据只读 key,或只暴露天然抗滥用的端点
数据库drop 表、改 schema按表白名单发凭据,默认只读

产品面还有三层反滥用20:注册验证(邮箱/手机)、中间件限流 (统计过去 X 分钟请求数,重则 timeout/ban)、prompt injection 护栏 (权限收窄 + 提示词写具体写严格)。注意最后一项的表述:护栏是「缓解」, 书里从没承诺「防住」——这个诚实的分寸和第 4 章「安全仍在发展中」一脉相承。

4. 作者的判断与证据​

  • 全章的服务选型(Supabase/LangSmith/Platform)是推荐而非跑分结论, 书也直接承认部署方式不止一种(免费自托管路线存在,但要自管数据库和 Redis)21。
  • match_documents 的 SQL、langgraph.json 的字段说明、部署表单的字段清单都是操作文档式的内容, 属于「照做即可」类;唯一带数字的承诺是 Production 档 500 req/s15。
  • 利益相关提醒再贴一次:Platform 与 LangSmith 都是 LangChain 公司的商业产品, 本章实质是官方推荐的部署路径(本库关于作者页,text/16-fm-about-the-authors.txt:11,搜「founding software engineer」)。

5. 边界与局限​

  • 成本模型缺席:token 计费、实例单价、多少并发配多少实例,全书没有一处给数—— 500 req/s 是唯一拿得出手的生产口径。
  • vector(1536) 直接写进建表语句,换嵌入模型需要改表;迁移已有数据的做法书中未提2。
  • stateless runs 的「重试保留记忆」与「后台任务从头重跑」双语义容易踩混, 书中一段话带过,工程上要自己写测试钉死10。
  • 安全清单未覆盖多租户隔离(thread 越权访问)与审计留痕;prompt injection 只有原则没有攻防示例。
  • 补充(不在书里,来自通用知识):2026 年的主流做法已普遍在部署前加一层 prompt injection 分类器与输出审查,比书中的「权限收窄+严格提示」更进一步。

6. 可带走的​

  1. 上线三件套:公网向量库、托管运行时、观测面——每个本地玩具件都有生产对应物;
  2. 两个环境变量(LANGCHAIN_TRACING_V2 + key)零代码接通全链路轨迹,调试期就该开;
  3. pgvector 的最小可用品=一张表 + 一个带 <=> 排序与 @> 过滤的检索函数;
  4. Platform 四模型一句话记法:Assistant 是图,Thread 是账本,Run 是一笔, Cron 是闹钟;
  5. 想持久化就必须先建 Thread;checkpoint 是「某时点的账本快照」,一切恢复操作围绕它;
  6. langgraph.json 三行配置 + GitHub 授权 = 部署;改版靠 revision,不靠重传;
  7. Studio 的独门本事是把轨迹从中段拎出来改——调试 agent 的正确姿势是「改历史」而不是「重跑全程」;
  8. 安全三原则按原样背:最小权限、预设滥用、纵深防御;三靶场各自先降权限再谈其他;
  9. 反滥用三层(验证/限流/护栏)是产品默认项,不是可选项;
  10. token 账要自己算:书里唯一的数字是 500 req/s,成本模型是你的作业。

7. 原文地图​

主题原书章原文位置
三服务选型Chapter 9text/12-fm-prerequisites.txt:15(搜「various services」)
环境变量与 tracing 开关Chapter 9text/12-fm-prerequisites.txt:39(搜「.env」) · text/12-fm-prerequisites.txt:46(搜「LANGCHAIN_TRACING_V2」)
Supabase 建表与维度Chapter 9text/12-fm-prerequisites.txt:83(搜「create table documents」) · text/12-fm-prerequisites.txt:87(搜「vector(1536)」)
match_documents 函数与语义解释Chapter 9text/12-fm-prerequisites.txt:95(搜「match_documents」) · text/12-fm-prerequisites.txt:124(搜「cosine similarity」)
过滤/排序/取数三步Chapter 9text/12-fm-prerequisites.txt:126(搜「JSON containment」)
SupabaseVectorStore 挂接Chapter 9text/12-fm-prerequisites.txt:154(搜「query_name」)
Platform 定位与扩缩Chapter 9text/12-fm-prerequisites.txt:230(搜「managed service」) · text/12-fm-prerequisites.txt:232(搜「horizontally scaling」)
平台级 double texting/后台/cronChapter 9text/12-fm-prerequisites.txt:234(搜「real-world interaction patterns」)
四数据模型(Assistant)Chapter 9text/12-fm-prerequisites.txt:266(搜「core data models」) · text/12-fm-prerequisites.txt:278(搜「configured instance of a CompiledGraph」)
Thread 与 checkpointChapter 9text/12-fm-prerequisites.txt:284(搜「accumulated state」)
Run 与 CronChapter 9text/12-fm-prerequisites.txt:290(搜「invocation of an assistant」) · text/12-fm-prerequisites.txt:296(搜「user-defined schedule」)
平台五流式模式Chapter 9text/12-fm-prerequisites.txt:314(搜「five streaming modes」) · text/12-fm-prerequisites.txt:318(搜「super-step」)
HITL 平台建议Chapter 9text/12-fm-prerequisites.txt:338(搜「catastrophic application outcomes」)
double texting 四配置Chapter 9text/12-fm-prerequisites.txt:344(搜「Reject」) · text/12-fm-prerequisites.txt:356(搜「Rollback」)
stateless runs 双重试语义Chapter 9text/12-fm-prerequisites.txt:368(搜「skips all checkpointing」) · text/12-fm-prerequisites.txt:372(搜「retried from scratch」)
webhooksChapter 9text/12-fm-prerequisites.txt:376(搜「completion webhooks」)
langgraph.json 与目录结构Chapter 9text/12-fm-prerequisites.txt:384(搜「langgraph.json」) · text/12-fm-prerequisites.txt:398(搜「my-app」)
本地 dev server 与 SDKChapter 9text/12-fm-prerequisites.txt:443(搜「langgraph dev」) · text/12-fm-prerequisites.txt:448(搜「2024」)
cURL multitask_strategy 示例Chapter 9text/12-fm-prerequisites.txt:472(搜「multitask_strategy」)
部署表单与 GitHub 授权Chapter 9text/12-fm-prerequisites.txt:550(搜「Import with GitHub」)
Production 500 req/sChapter 9text/12-fm-prerequisites.txt:558(搜「500 requests/second」)
revision 与 trace 图Chapter 9text/12-fm-prerequisites.txt:564(搜「new revision」) · text/12-fm-prerequisites.txt:566(搜「Trace Count」)
Studio 轨迹中段修改Chapter 9text/12-fm-prerequisites.txt:580(搜「halfway through the agent's trajectory」)
桌面版(Note)Chapter 9text/12-fm-prerequisites.txt:608(搜「Apple silicon」)
安全三原则Chapter 9text/12-fm-prerequisites.txt:618(搜「Limit permissions」) · text/12-fm-prerequisites.txt:624(搜「any way allowed by the permissions」) · text/12-fm-prerequisites.txt:626(搜「Defense in depth」)
三靶场Chapter 9text/12-fm-prerequisites.txt:632(搜「File access」) · text/12-fm-prerequisites.txt:636(搜「API access」) · text/12-fm-prerequisites.txt:640(搜「Database access」)
反滥用三层Chapter 9text/12-fm-prerequisites.txt:646(搜「Account creation verification」) · text/12-fm-prerequisites.txt:650(搜「Rate limiting」) · text/12-fm-prerequisites.txt:654(搜「Prompt injection」)

Footnotes​

  1. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 39–50 段(text/12-fm-prerequisites.txt:45,搜「for tracing」);「无需其他代码即可启用」的对应表述在第 10 章第 1033 段(text/13-ch10-chapter-10-testing-evaluation-monitoring-and-con.txt:1033,搜「no other code is required」)。 ↩

  2. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 83–90 段(text/12-fm-prerequisites.txt:87,搜「1536 works for OpenAI embeddings」)。 ↩ ↩2

  3. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 92–124 段,函数体在第 95–122 行(text/12-fm-prerequisites.txt:116,搜「documents.embedding <=> query_embedding」)。 ↩

  4. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 132–162 段(text/12-fm-prerequisites.txt:154,搜「query_name」)。 ↩

  5. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 230–232 段(text/12-fm-prerequisites.txt:232,搜「robust Postgres checkpointer」)。 ↩

  6. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 262–296 段(text/12-fm-prerequisites.txt:268,搜「Assistants」)。 ↩

  7. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 284 段(text/12-fm-prerequisites.txt:284,搜「called a checkpoint」)。 ↩

  8. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 298–310 段(text/12-fm-prerequisites.txt:300,搜「Several features」)。 ↩

  9. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 312–376 段(流式五模式第 314–334 行;HITL 第 336–338 行;double texting 第 340–358 行;stateless 第 360–372 行;webhooks 第 374–376 行)。 ↩

  10. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 372 段(text/12-fm-prerequisites.txt:372,搜「keeping memory intact」)。 ↩ ↩2

  11. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 429–532 段(dev 命令输出第 447–449 行,cURL 第 455–476 行,SDK 第 482–530 行)。 ↩

  12. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 384–427 段(text/12-fm-prerequisites.txt:415,搜「what each of the properties mean」)。 ↩

  13. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 396–409 段(目录树)与第 411 行(text/12-fm-prerequisites.txt:411,搜「same level or higher」)。 ↩

  14. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 534–564 段(text/12-fm-prerequisites.txt:546,搜「three form fields」)。 ↩

  15. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 558 段(text/12-fm-prerequisites.txt:558,搜「500 requests/second」)。 ↩ ↩2

  16. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 564–572 段(text/12-fm-prerequisites.txt:566,搜「Trace Count summary chart」)。 ↩

  17. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 578–588 段(text/12-fm-prerequisites.txt:580,搜「modify an agent result」)。 ↩

  18. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 612–628 段(text/12-fm-prerequisites.txt:620,搜「Scope permissions specific」)。 ↩

  19. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 630–642 段(text/12-fm-prerequisites.txt:634,搜「delete files」)。 ↩

  20. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 644–656 段(text/12-fm-prerequisites.txt:644,搜「exponential costs」)。 ↩

  21. 出处:「Chapter 9. Deployment: Launching Your AI Application into Production」第 258 段(text/12-fm-prerequisites.txt:258,搜「free self-hosted deployment」)。 ↩