LangChain Go 使用 Google AlloyDB 持久化 Chat Message History完整实战指南【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo本指南围绕 langchaingo 仓库中 google-alloydb-chat-message-history-example 示例讲解如何将 Google Cloud 的 AlloyDB for PostgreSQL 作为 Go 版 LangChain 对话记忆ChatMessageHistory的持久化后端。读完本文你将掌握从环境配置、连接池初始化、建表到消息增删查改的完整链路并深入理解memory/alloydb与util/alloydbutil两个包的源码实现原理。背景为什么用数据库承载对话记忆在构建 LLM 应用时多轮对话需要把历史消息保存下来才能在下一轮请求中作为上下文提供给模型。LangChain Go 通过 schema.ChatMessageHistory 接口抽象了这一能力其定义了六个核心方法AddMessage追加一条llms.ChatMessage消息AddUserMessage/AddAIMessage便捷地追加用户或 AI 消息字符串Clear清空全部消息Messages取回全部消息SetMessages整体替换现有消息。默认的 memory 实现把消息放在进程内存里进程重启即丢失。当应用需要多实例共享、会话跨进程恢复时就需要一个数据库后端。本示例展示的正是将 AlloyDB for PostgreSQLGoogle Cloud 的托管 Postgres 兼容数据库作为该接口实现的存储层。准备工作前置条件与运行环境在运行示例前需要完成以下云环境准备对应 memory/alloydb/README.md 中的 Quick Start 步骤创建或选择一个 Google Cloud 项目为项目启用结算billing在控制台启用 AlloyDB API通过gcloud auth application-default login完成 Cloud SDK 认证。代码层面examples/go.mod 显示该示例基于go 1.24.3依赖github.com/tmc/langchaingo v0.1.14-pre.4并通过cloud.google.com/go/alloydbconn建立安全连接。仓库中memory/alloydb包要求Go 版本不低于 1.22.0。示例的模块声明位于examples/google-alloydb-chat-message-history-example/go.mod进入该目录即可独立构建运行。第一步配置环境变量示例程序通过环境变量注入连接信息与业务参数运行时任何一项缺失都会以log.Fatal立即退出见 getEnvVariables 函数export PROJECT_IDyour project Id export ALLOYDB_USERNAMEyour user export ALLOYDB_PASSWORDyour password export ALLOYDB_REGIONyour region export ALLOYDB_CLUSTERyour cluster export ALLOYDB_INSTANCEyour instance export ALLOYDB_DATABASEyour database export ALLOYDB_TABLEyour tablename export ALLOYDB_SESSION_IDyour sessionID其中PROJECT_ID、ALLOYDB_REGION、ALLOYDB_CLUSTER、ALLOYDB_INSTANCE用于定位 AlloyDB 实例可在 Google Cloud 控制台的 AlloyDB 集群页面找到ALLOYDB_TABLE指定存放消息的数据表名ALLOYDB_SESSION_ID用于区分不同的会话是消息读写隔离的关键。第二步初始化 PostgresEngine 连接引擎连接的核心是alloydbutil.PostgresEngine它内部持有一个*pgxpool.Pool连接池见 util/alloydbutil/engine.go。示例中的初始化方式pgEngine, err : alloydbutil.NewPostgresEngine(ctx, alloydbutil.WithUser(username), alloydbutil.WithPassword(password), alloydbutil.WithDatabase(database), alloydbutil.WithAlloyDBInstance(projectID, region, cluster, instance), ) if err ! nil { log.Fatal(err) }底层连接原理从 createPool 实现 可以看到连接建立的完整逻辑使用alloydbconn.NewDialer创建连接拨号器DSN 为user... password... dbname... sslmodedisable依据传入的项目、区域、集群、实例拼接出 AlloyDB 实例 URIprojects/project/locations/region/clusters/cluster/instances/instance通过自定义DialFunc调用d.Dial建立安全隧道默认使用公网 IPPUBLIC可通过WithIPType(PRIVATE)切换到私网最终基于pgxpool.NewWithConfig生成连接池。其他可用 Optionutil/alloydbutil/options.go 定义了全部引擎选项Option作用WithAlloyDBInstance(project, region, cluster, instance)设置实例定位信息WithUser/WithPassword设置数据库账号密码WithDatabase设置目标数据库名WithPool直接注入外部创建的pgxpool.Pool适用于 AlloyDB Omni 或自定义连接池WithIPType指定公网PUBLIC默认或私网PRIVATE连接WithIAMAccountEmail使用 IAM 账号邮箱认证关于认证方式getUser 函数 展示了三种分支优先使用用户名 密码若提供WithIAMAccountEmail则走 IAM 认证DSN 中不再含密码并追加alloydbconn.WithIAMAuthN()若两者皆无则尝试通过默认凭据获取服务账号邮箱。这意味着示例展示的是最简单的账号密码方式实际生产环境还可以切换到 IAM 认证以规避口令管理。第三步创建消息表AlloyDB 要求消息表具备固定结构。示例调用err pgEngine.InitChatHistoryTable(ctx, tableName)对应 InitChatHistoryTable 实现其生成的 DDL 为CREATE TABLE IF NOT EXISTS schema.table ( id SERIAL PRIMARY KEY, session_id TEXT NOT NULL, data JSONB NOT NULL, type TEXT NOT NULL );表结构中的四个列与ChatMessageHistory.validateTable的校验逻辑一一对应见 memory/alloydb/chat_message_history.goid为整数自增主键保证消息读取顺序session_id用于会话隔离data以 JSONB 存储消息正文type记录消息类型。创建时默认使用publicschema也可通过WithSchemaName指定自定义 schema。第四步创建 ChatMessageHistory 并验证表结构cmh, err : alloydb.NewChatMessageHistory(ctx, pgEngine, tableName, sessionID) if err ! nil { log.Fatal(err) }NewChatMessageHistory 会做三件事校验必需参数连接池非空、表名非空、会话 ID 非空缺失即返回明确错误如table name must be provided、session ID must be provided应用WithSchemaName等可选配置默认 schema 为public见 chat_message_history_options.go调用validateTable查询information_schema确认表存在且四个必需列的名称与类型完全匹配否则返回形如error, column data is missing in table xxx的错误。值得注意的是var _ schema.ChatMessageHistory ChatMessageHistory{}这一编译期断言memory/alloydb/chat_message_history.go它保证alloydb.ChatMessageHistory完整实现了上文提到的标准接口从而可以无缝嵌入 LangChain Go 的对话链路。第五步消息的增、查、改、清示例随后演示了针对同一sessionID的完整消息生命周期操作。逐条添加消息aiMessage : llms.AIChatMessage{Content: test AI message} humanMessage : llms.HumanChatMessage{Content: test HUMAN message} err cmh.AddUserMessage(ctx, aiMessage.GetContent()) err cmh.AddUserMessage(ctx, humanMessage.GetContent()) printMessages(ctx, cmh)底层 addMessage 先将内容 JSON 序列化再执行INSERT INTO schema.table (session_id, data, type) VALUES ($1, $2, $3)。此外还提供AddMessage接收任意llms.ChatMessage与AddAIMessage固定标记为 AI 类型等便捷方法。批量添加消息multipleMessages : []llms.ChatMessage{ llms.AIChatMessage{Content: first AI test message from AddMessages}, llms.AIChatMessage{Content: second AI test message from AddMessages}, llms.HumanChatMessage{Content: first HUMAN test message from AddMessages}, } err cmh.AddMessages(ctx, multipleMessages)AddMessages 使用pgx.Batch把所有插入语句打包后经SendBatch一次提交避免逐条往返的网络开销是批量写入的高效路径。查询消息示例中printMessages辅助函数调用cmh.Messages(ctx)遍历输出。对应的 Messages 实现 执行SELECT ... WHERE session_id $1 ORDER BY id确保消息按写入顺序返回随后反序列化 JSON 内容并根据type字段还原为AIChatMessage、HumanChatMessage或SystemChatMessage。若遇到未知类型则返回unsupported message type错误。覆盖消息overWrittingMessages : []llms.ChatMessage{ llms.AIChatMessage{Content: overwritten AI test message}, llms.HumanChatMessage{Content: overwritten HUMAN test message}, } err cmh.SetMessages(ctx, overWrittingMessages)SetMessages 的语义是先清空该会话旧消息再批量写入新消息实现上先调用Clear再走批量插入适合重写整段对话上下文的场景。清空会话消息err cmh.Clear(ctx)Clear 执行DELETE FROM schema.table WHERE session_id $1只删除当前会话的消息不影响其他会话数据。运行示例在配置好环境变量后进入示例目录执行cd examples/google-alloydb-chat-message-history-example go run google_alloydb_chat_message_history_example.go程序会依次打印三批消息初始添加的两条、批量追加后的五条含前两条、覆盖后的两条最后清空会话。仓库中的集成测试 memory/alloydb/chat_message_history_test.go 验证了相同路径测试用例覆盖了表名缺失报错会话 ID 缺失报错以及AddMessage、AddAIMessage、AddUserMessage、Clear的正常调用链由于需要真实数据库测试在缺少ALLOYDB_USERNAME等环境变量时会自动t.Skip跳过。关键特性小结对照原示例文档这套方案的核心价值可以归纳为AlloyDB 深度集成alloydbutil负责与 AlloyDB 实例建立安全连接池memory/alloydb负责消息的存储与管理职责清晰会话级消息管理所有读写操作都以session_id为维度天然支持多会话并存与隔离完整操作能力覆盖逐条添加、批量添加、整体覆盖、查询与清空五种操作满足对话记忆的常见需求源码级可靠性创建时即校验表结构与列类型接口实现有编译期断言保障批量操作利用pgx.Batch提升性能。如需进一步了解引擎 API 的更多细节可继续阅读 util/alloydbutil/options.go 与 memory/alloydb/chat_message_history_options.go仓库中还提供了对应的 Postgres Vector Store 示例可在同一 AlloyDB 实例上同时承载向量检索与对话记忆两类数据。【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考