LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. LangGraph 把記憶明確拆成兩套各司其職的組件:Checkpointer(檢查點) 管「當前這一個對話窗口(thread_id)聊到了哪一步」,Store(長期存儲) 管「同一個用戶(user_id)打開新窗口也該記住的長期偏好」。
  2. 上線生產首選開源免費的 langgraph-checkpoint-postgres:無需購買商業託管平台(費用邊界見 /guides/langgraph-pricing-open-source-vs-platform),直接連你們自己的 PostgreSQL 即可支撐多節點無狀態擴容。
  3. 首次連上空數據庫後必須先調一次 .setup():用於自動創建存放快照與記憶鍵值所需的系統數據表。
  4. FastAPI 異步生產服務請統一用異步版 AsyncPostgresSaver 與 AsyncPostgresStore,避免同步數據庫驅動阻塞整個異步事件循環。

Checkpointer 與 Store 雙層記憶對比

圖:本站根據 LangGraph 官方文檔 Persistence 與 Memory 整理的示意圖

本文根據 LangChain / LangGraph 官方文檔《Persistence》《Memory》與 langgraph-checkpoint-postgres 倉庫文檔整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。

適用於誰

  • 搜「langgraph postgres checkpointer」「langgraph 長期記憶 store」「langgraph 持久化」的後端開發者;
  • 在入門示例(見 /guides/langgraph-quickstart-install-first-graph)裏用通了內存儲存器,準備把服務搬上多實例生產容器、解決重啟丟記錄問題的人;
  • 發現用戶開一個新對話窗口(換了新 thread_id)後,智能體就把該用戶的老習慣全忘了,想知道怎麼跨會話共享用戶畫像的人。

一、先徹底分清:什麼時候查 Checkpointer、什麼時候讀寫 Store

很多人在做聊天應用時只配了 checkpointer,上線後馬上遇到一個典型尷尬:用戶小張昨天在「會話 A」裏交代過「我是素食主義者、報告一律用表格展示」;今天小張點左上角「新建對話」開啟了「會話 B」(分配了全新的 thread_id),智能體瞬間把這兩條偏好忘得一乾二淨。

原因就在於兩層存儲的鍵維度完全不同:

  • Checkpointer(按 thread_id 隔離):儲存的是每一次節點跳轉後的完整 State 快照。它的本職工作是支撐多輪追問、人工審批掛起恢復(見 /guides/langgraph-human-in-the-loop-interrupt-guide)與斷點時間旅行。不同 thread_id 之間互不可見;
  • Store(按自定義命名空間如 ("memories", user_id) 組織):它是一個獨立於具體線程之外的跨會話文檔庫(還可選配向量語義檢索)。無論小張新建多少個聊天窗口,只要節點按他的 user_id 去 store 裏查,就能讀出他之前沉澱下來的個人檔案。

接入 PostgreSQL 持久化四步流程

圖:本站根據 langgraph-checkpoint-postgres 官方文檔 整理的示意圖

二、安裝依賴與連接 PostgreSQL 雙層存儲示例

如果你只是在單機寫桌面小工具,裝 langgraph-checkpoint-sqlite 落盤成單個本地文件就夠用;如果是多實例後端服務,直接安裝官方的 PostgreSQL 包與底層 psycopg(v3)驅動:

bash
pip install -U langgraph langgraph-checkpoint-postgres "psycopg[binary,pool]"

下面的異步代碼展示瞭如何同時啟用 AsyncPostgresSaver 和 AsyncPostgresStore,並在節點函數里通過類型註解自動拿到 BaseStore 實例讀寫跨會話記憶:

python
import asyncio
import uuid
from langchain_core.runnables import RunnableConfig
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
from langgraph.store.postgres.aio import AsyncPostgresStore
from langgraph.store.base import BaseStore

DB_URI = "postgresql://postgres:[email protected]:5432/agent_db"

async def chat_node(state: MessagesState, config: RunnableConfig, *, store: BaseStore):
    user_id = config["configurable"]["user_id"]
    namespace = ("user_profiles", user_id)

    # 1. 跨線程讀取該用戶過往儲存的所有長期偏好
    saved_items = await store.asearch(namespace)
    prefs = [item.value.get("note", "") for item in saved_items]

    last_text = state["messages"][-1].content
    # 2. 若用戶本輪明確交代記住某事,寫入跨會話 Store
    if "請記住:" in last_text:
        await store.aput(namespace, str(uuid.uuid4()), {"note": last_text})

    summary = ";".join(prefs) if prefs else "暫無歷史偏好"
    reply = f"已讀取您的跨會話檔案({summary}),收到本輪消息:{last_text}"
    return {"messages": [("assistant", reply)]}

async def main():
    async with (
        AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer,
        AsyncPostgresStore.from_conn_string(DB_URI) as store,
    ):
        # 首次連接空庫時執行建表遷移(冪等操作)
        await checkpointer.setup()
        await store.setup()

        builder = StateGraph(MessagesState)
        builder.add_node("chat", chat_node)
        builder.add_edge(START, "chat")
        builder.add_edge("chat", END)

        graph = builder.compile(checkpointer=checkpointer, store=store)

        # 會話 1:寫入一條長期偏好
        cfg_thread_1 = {"configurable": {"thread_id": "t-001", "user_id": "u_zhang"}}
        await graph.ainvoke({"messages": [("user", "請記住:報表統一用周度口徑")]}, cfg_thread_1)

        # 會話 2:換了全新的 thread_id,依然能從 store 讀出剛才存下的偏好
        cfg_thread_2 = {"configurable": {"thread_id": "t-002", "user_id": "u_zhang"}}
        out = await graph.ainvoke({"messages": [("user", "幫我生成本週彙總")]}, cfg_thread_2)
        print(out["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

三、生產環境連接池與 CLI 部署避坑提醒

  1. 手動建連接池必配兩個參數:from_conn_string 適合快速測試;在長生命週期的 FastAPI 應用生命週期(lifespan)裏自建 AsyncConnectionPool 時,官方文檔特別強調必須在連接參數裏打開 autocommit=True 和 row_factory=dict_row,否則 .setup() 建表事務不提交或讀取行字段時報鍵錯誤;
  2. 與 langgraph.json 託管模式區分開:如果你是用官方 CLI 服務啟動(配置見 /guides/langgraph-json-config-guide),服務端框架會自動接管底層的 checkpointer 與 store 注入,節點函數里照常聲明 *, store: BaseStore 即可直接用,不需要在 compile() 時手工傳連接串;
  3. 控制檢查點表體積膨脹:高頻工具循環每走一步都會寫一行快照,對已經完結超過幾十天的陳舊臨時會話,建議定期按 thread_id 清理歸檔。日常用大模型輔助編寫數據庫清理腳本或排查連接池異常時,個人官方訂閱說明也可參考 /chongzhi/chatgpt-plus。

常見問題

Q:Store 支持按自然語言語義搜尋幾百條歷史記憶嗎?

支持。在初始化 PostgresStore(或 InMemoryStore)時傳入 index={"embed": 嵌入模型, "dims": 向量維度} 並確保 PostgreSQL 開啟了 pgvector 擴展後,store.asearch(namespace, query="飲食習慣") 就會自動執行向量相似度檢索,只召回最相關的幾條記憶省下上下文。

Q:報 psycopg.OperationalError 連不上本地數據庫怎麼查?

先確認連接串裏的端口、庫名是否已提前手動 CREATE DATABASE agent_db;(.setup() 只負責在已有庫內建表,不會替你新建數據庫本身),並核對密碼含特殊符號時是否做了 URL 編碼。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔:Persistence & Memory Store — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  3. 03

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  4. 04

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  5. 05

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0
  6. 06

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  3. 03

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0
  6. 06

    CrewAI 入門教學:Agent 角色、Task 任務、執行流程(Process)與第一個團隊示例

    CrewAI 是主打「擬人化角色分工」的 Python 多智能體開源框架。本文按官方文檔講清安裝要求、Agent(角色/目標/背景)、Task(任務描述與預期輸出)和 Process(順序接力與經理層級模式)的配合邏輯,並給出最小可運行代碼。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~