langchain-openviking 集成指南用 LangChain/LangGraph 接入 OpenViking 的 Agent 记忆、RAG 与 Skills【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikinglangchain-openviking是 OpenViking 官方维护的 LangChain / LangGraph 集成包它把框架适配逻辑与 OpenViking 服务端彻底解耦所有远程访问统一通过轻量的openviking-sdk完成。阅读本文后你将掌握从安装、客户端连接管理到 Retriever 检索、Message History 会话记忆、LangGraph Store、工具工厂与 Context Middleware 的完整接入方法并能在自己的 Agent 应用中直接落地记忆 知识库 技能的统一上下文方案。包结构与定位该包位于仓库的 integrations/langchain 目录采用src布局源码集中在 integrations/langchain/src/langchain_openviking/模块划分如下模块文件提供的核心能力retrievers.pyOpenVikingRetriever把 OpenViking 检索结果包装为 LangChainDocumenttools.pycreate_openviking_tools生成viking_*前缀的 LangChain 工具集history.pyOpenVikingChatMessageHistory基于 OpenViking Session 的聊天历史recording.pyOpenVikingSessionRecorder与提交策略、部分写入错误模型store.pyOpenVikingStoreLangGraphBaseStore的实现middleware.pyOpenVikingContextMiddlewareLangGraph Agent 中间件context.pyOpenVikingSessionContextAssembler、OpenVikingContextRunnable等高层生命周期助手client.pyOpenVikingConnection、连接句柄、提交策略与通用调用辅助testing.pyInMemoryOpenVikingClient用于无服务端测试_uri.pyURI 分类工具classify_uri包元数据定义在 integrations/langchain/pyproject.toml基础依赖为langchain-core1.0.0,2.0.0、openviking-sdk0.1.1、pydantic2.0.0要求 Python 3.10LangGraph 相关能力通过可选 extra 提供。包入口 integrations/langchain/src/langchain_openviking/init.py 采用延迟导入__getattr__设计保证仅安装langchain-core时即可使用 Retriever、Tools、Message History 与 Context 相关组件而OpenVikingContextMiddleware只在检测到langchain时才暴露。安装按需选择安装方式。若只需 LangChain 的 Retriever、Tools、Message History 与 Context Wrapperpip install langchain-openviking若还需要 LangGraph Store 与 Middleware则安装langgraphextrapip install langchain-openviking[langgraph]对应的可选依赖在 pyproject.toml 中声明为langchain1.0.0,2.0.0与langgraph1.0.0,2.0.0。若在缺少对应框架依赖的情况下调用相关组件client.py 中的missing_dependency会抛出OptionalDependencyError并给出明确的安装提示pip install langchain-openviking[langgraph]。快速开始第一个 RetrieverREADME 给出的最小示例展示了同步客户端的完整生命周期from langchain_openviking import OpenVikingRetriever from openviking_sdk import SyncHTTPClient client SyncHTTPClient( urlhttp://127.0.0.1:1933, api_keyyour-user-api-key, ) client.initialize() retriever OpenVikingRetriever( clientclient, target_uriviking://~/memories, ) try: documents retriever.invoke(What deployment preferences should I remember?) finally: client.close()这里需要特别注意三点viking://~Home 别名示例使用viking://~/memoriesServer 会将其展开为当前调用方自己的用户空间因此需要支持viking://~的 Server 版本。不带 uid 的旧写法viking://user/memories会被新版 Server 拒绝要访问其他用户请显式传入viking://user/uid/...。端口 1933是 OpenViking 本地服务的默认 HTTP 端口api_key需替换为用户自己的 API Key。调用方传入的 client 仍归调用方所有retriever.close()/aclose()只释放适配器内部创建的资源不会关闭你传入的客户端。仓库提供了可直接运行的确定性示例见 examples/langchain-langgraph/langchain/rag/quick_app.py。该示例用InMemoryOpenVikingClient预置了两条上下文viking://~/memories/preferences/deploy_color.md与viking://resources/runbooks/langchain.md将OpenVikingRetriever作为 LCEL 链的中间环节注入 promptretriever OpenVikingRetriever( clientclient, target_uri[viking://~/memories, viking://resources], limit4, content_modeauto, ) return ( { context: retriever | RunnableLambda(_format_docs), question: RunnablePassthrough(), } | prompt | model | StrOutputParser() )注意target_uri支持传入 URI 列表可同时检索多个命名空间。Client 所有权与连接管理README 明确了两类 client 的所有权规则通过client或async_client传入的 client保持调用方所有适配器不会在close()/aclose()时关闭它通过url创建的 client由适配器管理可用各适配器文档中说明的close()/aclose()释放。底层机制在 client.py 的OpenVikingConnectiondataclass 中定义它统一承载所有连接参数client、async_client、url、api_key、account、user、user_id、actor_peer_id、timeout默认 60.0 秒、extra_headers与auto_initialize默认 True。所有适配器Retriever、Store、Tools、History都通过这一连接描述符懒创建 client。值得关注的是 client.py 中实现的OpenVikingClientHandle与OpenVikingAsyncClientHandle懒初始化client 在首次调用时才创建get()避免不必要的启动开销一次性恢复one-shot recovery当调用抛出可恢复错误DEADLINE_EXCEEDED、UNAVAILABLE、ConnectionError、TimeoutError、httpx 传输错误、或event loop is closed等运行时错误见_RECOVERABLE_OPENVIKING_CODES与_is_recoverable_client_error时句柄会重置旧 client 并重试一次只有_RETRYABLE_READ_METHODS中列出的只读方法find、search、read、ls、stat、glob、get_session等才会重试写操作不会被盲目重放异步句柄是 event-loop-local 的OpenVikingAsyncClientHandle.get()会校验调用方事件循环跨 loop 复用会抛出RuntimeError。这也是_async_client_cache.py中LoopScopedAsyncClientCache存在的原因异步 client 按事件循环作用域缓存保证每个 loop 拿到自己创建的 client。OpenVikingRetriever 详解OpenVikingRetriever继承BaseRetriever把 OpenViking 的检索结果转换为 LangChainDocument核心实现位于 retrievers.py。它支持的配置字段与含义如下字段默认值说明target_uri检索范围 URI支持字符串或 URI 列表search_modefindfind无状态语义检索或search会话感知检索session_idNone配合search_modesearch使用limit10返回结果条数上限score_thresholdNone后端相关性分数阈值filterNone结构化过滤条件dictcontext_types(memory, resource, skill)允许的上下文类型对应 OpenViking 的三大类上下文content_modeautoauto/abstract/overview/read四种内容深度max_content_chars12_000每条内容最大字符数超出截断并追加...[truncated]metadata_prefixopenvikingDocument 元数据前缀tagsNone检索标签过滤检索调用链_get_relevant_documents→call_openviking(client, search or find, ...)→ 通过iter_result_items按context_types过滤 → 逐条生成Document。每个Document的元数据会带上source即 OpenViking URI以及openviking_uri、openviking_context_type、openviking_level、openviking_category、openviking_score、openviking_match_reason、openviking_abstract、openviking_overview等字段retrievers.py方便下游追踪溯源。content_mode的语义在_content_for_item中实现abstract取摘要、overview取概述、read会调用read方法读取完整内容并在失败时回退到概述、auto则对 level 2 的内容执行完整读取、其余返回概述。异步路径ainvoke/_aget_relevant_documents走同样的逻辑只是通过OpenVikingAsyncClientHandle与asyncio.to_thread避免阻塞事件循环。基于 Session 的聊天历史OpenVikingChatMessageHistory实现BaseChatMessageHistory位于 history.py把 LangChain 的聊天历史持久化到 OpenViking Session。构造参数包括session_id必填OpenViking 会话标识连接参数client/async_client/url/api_key/account/user/user_id/actor_peer_id/timeout/extra_headers/auto_initializetoken_budget默认 128_000读取会话上下文时允许的 token 预算commit_policyOpenVikingCommitPolicy控制消息写入后的提交时机context_parts_provider/context_parts_acknowledger回调用于把检索到的上下文context_parts随消息一起持久化并确认peer_id/peer_id_provider消息归属的 peer 标识。它提供messages/aget_messages读取内部调用get_session_context并按token_budget截取、add_messages/aadd_messages写入通过OpenVikingSessionRecorder批量记录、clear/aclear清空调用delete_session后重建 Session。系统消息属于运行时策略而非对话记忆因此永远不会被持久化persist_system_messages恒为 False。commit_policy的类型定义在 client.pydataclass(slotsTrue) class OpenVikingCommitPolicy: mode: Literal[never, always, pending_tokens] never pending_token_threshold: int 8_000apply_commit_policy/aapply_commit_policy实现三种模式never不提交always每次写入后立即commit_sessionpending_tokens在会话待提交 token 数达到pending_token_threshold默认 8000时才提交用于控制提交频率。LangGraph Store把持久化存储接到 OpenVikingOpenVikingStore实现 LangGraphBaseStore位于 store.py让 LangGraph 图的持久化存储直接落在 OpenViking 上。其存储模型非常有特色每个(namespace, key)条目对应两条 OpenViking 记录root_uri/data/namespace/key.jsonJSON 数据记录含namespace、key、value、created_at、updated_atroot_uri/index/namespace/key.mdMarkdown 投影文档供 OpenViking 语义检索建立索引root_uri默认是viking://~/memories/langgraph_store同样依赖viking://~Home 别名index参数支持True、False或字段路径列表如[user.name, status]用于控制索引文档投影哪些字段避免把大值全部写入索引search_fetch_limit默认 50控制语义搜索的预取条数。它实现了 LangGraphBaseStore的全部核心接口get/put/delete/search/list_namespaces/batch/abatch。其中search在无query时按更新时间倒序返回带query时走_semantic_search在 index 前缀 URI 上调用find再回读 JSON 记录。过滤表达式支持$eq/$ne/$gt/$gte/$lt/$lte/$in等操作符_compare实现。需要说明的是TTL 不被支持put(..., ttl...)会抛出NotImplementedError。工具工厂create_openviking_toolscreate_openviking_toolstools.py把 OpenViking 的常用 Agent 原语封装为 LangChainStructuredTool。工具名统一使用viking_*前缀让模型看到与 OpenViking 插件/MCP 一致的语义操作工具名底层调用用途viking_findfind无状态语义检索viking_searchsearch会话感知语义检索可传session_idviking_browsels/glob列出命名空间/目录子项支持 glob 模式viking_readread/abstract/overview读取文件/文档 URI支持内容深度选择viking_grepgrep对文件内容做 grep 式搜索viking_archive_searchget_session_archive等检索已提交的会话归档上下文viking_archive_expandget_session_archive按 archive_id 展开归档viking_storecreate_session/add_message/commit_session追加持久化消息可自动建会话viking_add_resourceadd_resource导入 URL、仓库、文件等资源viking_add_skilladd_skill注册可复用技能viking_healthget_status/is_healthy健康检查viking_forgetrm删除 URI仅限受信 Agent 使用工具工厂支持按profile选择工具集_profile_tool_namesretrieval只读检索工具 viking_healthadmin检索工具 viking_store/viking_add_resource/viking_add_skill/viking_health/viking_forgetagent默认检索工具 viking_store/viking_add_resource/viking_add_skill/viking_health不含viking_forget。也可用tool_names显式指定工具列表allow_forgetTrue可额外追加viking_forget。写操作工具viking_store、viking_add_resource的 docstring 中明确提示这些是写操作面向用户的主机应仅在确认记住/保存工作流时暴露给模型普通对话捕获应由生命周期钩子处理。此外viking_add_resource对本地路径做了安全处理HTTP 客户端无法上传不存在的本地路径时会返回结构化的local_paths_not_supported_for_http_server错误提示_resolve_resource_source会先解析file://URI、展开~并区分远程资源与本地路径。LangGraph 中间件与上下文生命周期对于完整的 Agent 应用包提供了OpenVikingContextMiddlewaremiddleware.py它在 LangGraph 的扩展点上复刻 OpenClaw 式生命周期模型调用前注入召回recallAgent 执行后按需捕获会话capture。它要求 LangGraph session id通过config{configurable: {thread_id: ...}}、state[session_id]或session_id_resolver提供否则抛出_SESSION_ID_ERROR。配合使用的还有 context.py 中的OpenVikingAssembledContext上下文块 结构化 context_parts 会话上下文 召回文档与OpenVikingSessionContextAssembler。同步/异步写锁池_SyncSessionWriteLockPool/_AsyncSessionWriteLockPool会按 session_id 串行化写入避免并发写冲突。召回文档可通过context_parts_from_documentshistory.py转换为 OpenVikingContextPart随消息一并持久化实现召回即记忆。会话录制与部分写入OpenVikingSessionRecorderrecording.py负责把 LangChain 消息批量写入 OpenViking Session配套模型OpenVikingRecordResult记录已写入消息数、已消费输入消息数、上下文是否已附加OpenVikingPartialWriteError当批量写入或提交失败时抛出携带已确认的进度messages_written、input_messages_consumed、context_attached、commit_pending调用方可用它安全重试而不重复写入OpenVikingCancellationProgress把录制进度挂到原始asyncio.CancelledError上get_openviking_cancellation_progress可在取消后查询进度。单批最大写入量为MAX_RECORDING_BATCH_SIZE 100条消息。兼容迁移与更多示例完整openviking发行包会保留原有的openviking.integrations.langchain导入路径并转发到本包openviking/integrations/langchain方便现有应用平滑迁移无需改代码。仓库还提供了多种可直接运行的示例examples/langchain-langgraphlangchain/rag/quick_app.pyRetriever 驱动的 RAG 链langchain/message-history/quick_app.pyMessage History 示例langchain/context-backend/quick_app.py上下文后端示例langgraph/agent/quick_app.py在 LangGraph StateGraph 中用OpenVikingStorecreate_openviking_tools做召回节点与存储查询langgraph/agent/live_app.py真实模型版langgraph/middleware/quick_app.py中间件接入示例。例如 langgraph/agent/quick_app.py 展示了典型组合用法OpenVikingStore.put((demo, user), deployment, {...})写入存储create_openviking_tools(client..., profileretrieval)生成viking_find工具在recall节点里先调用工具检索、再store.search补充语义查询最后把上下文拼进 prompt。小结langchain-openviking把 OpenViking 的记忆 RAG 技能统一上下文能力完整映射到 LangChain / LangGraph 生态Retriever 负责语义召回Message History 与 Session Recorder 负责会话记忆持久化Store 提供符合 LangGraph 规范的键值存储工具工厂把检索/写入/资源管理暴露给模型Middleware 则把召回与捕获接入完整 Agent 生命周期。配合viking://~Home 别名、清晰的 client 所有权模型与内置的错误恢复机制开发者可以用少量代码把 OpenViking 变成自己 Agent 应用的持久上下文后端。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考