通用 OpenAI 兼容接入

通用 OpenAI 兼容接入

本节摘要:五类接入里最通用的一类——任意说 OpenAI 协议的 Agent,都能用第 9 章 SDK 四步法接入。本节讲清这种「通用接入」的适用场景(自研 Agent、说 OpenAI 协议的任意 Agent)、它的可控性收益(完全控制上下文)与代码成本(要自己写四步),并给出一个通用接入的最小骨架。这是「我有自己的 Agent,想接记忆」的标准答案。

一、什么是「OpenAI 兼容」

大量 Agent 框架与 LLM 服务都采用「OpenAI 协议」(即 OpenAI 的 Chat Completions API 格式)作为通用接口。这意味着只要你的 Agent 说这个协议,就能用统一方式接入记忆:

OpenAI 兼容的普遍性
  说 OpenAI 协议的:
    ├─ 自研 Agent(用 OpenAI SDK 调 LLM)
    ├─ 各种开源 Agent 框架(大量兼容 OpenAI 格式)
    ├─ 各类 LLM 服务(大量提供 OpenAI 兼容接口)
    └─ 甚至 Claude/Gemini 等也常通过兼容层用 OpenAI 格式
  
  → 「OpenAI 兼容」事实上的通用接口
​

关键概念:OpenAI 协议成了事实标准——「说这个协议」的 Agent 多到几乎覆盖所有自研场景。所以「通用 OpenAI 兼容接入」几乎等于「任意自研 Agent 接入」,这是为什么本节是五类接入里覆盖面最广的一类。

二、通用接入用 SDK 四步法

通用接入不用代理层(那个针对特定成熟产品),而用第 9 章 SDK 四步法——因为你「能改自己的 Agent」:

通用接入的逻辑
  你的 Agent(能改源码)
    ↓ 用 SDK 四步法:
    ├─ 召回(注入两区块)
    ├─ 捕获(工具暴露 + 对话回写)
    ├─ 工具暴露
    └─ 错误降级
    ↓
  接入记忆系统
​

三、通用接入的最小骨架

一个基于 OpenAI 协议 + SDK 四步法的最小接入骨架(概念性):

# 概念性骨架(Python + OpenAI SDK 风格)
from openai import AsyncOpenAI
from memory_core import MemoryCoreClient

llm = AsyncOpenAI(base_url="...", api_key="...")
memory = MemoryCoreClient(endpoint="...", key="...")

async def chat(user_message, session_ctx):
    # ① 召回(降级包裹)
    try:
        memories = await memory.recall(query=user_message, **session_ctx)
        # 注入两区块:append(稳定) + prepend(动态L1)
        sys_prompt = build_append(memories.persona_scene)  # 稳定
        user_with_prepend = build_prepend(user_message, memories.l1)  # 动态
    except Exception:
        sys_prompt = "你是助手"
        user_with_prepend = user_message

    # ③ 工具暴露
    try:
        tools = await memory.list_tools(**session_ctx)
        tools_oai = convert_to_openai_tools(tools)  # 转成 OpenAI tools 格式
    except Exception:
        tools_oai = []

    # 推理(OpenAI 协议)
    resp = await llm.chat.completions.create(
        model="...",
        messages=[
            {"role": "system", "content": sys_prompt},
            {"role": "user", "content": user_with_prepend},
        ],
        tools=tools_oai,  # 模型按需调用
    )
    reply = resp.choices[0].message.content

    # ② 捕获(降级,不阻塞)
    try:
        await memory.capture(
            conversation={"user": user_message, "agent": reply},
            **session_ctx,
        )
    except Exception:
        pass

    return reply
​

这个骨架体现了:召回(两区块注入)、工具(转 OpenAI 格式)、捕获(回写)、降级(每步 try)。任何说 OpenAI 协议的 Agent,套这个骨架即可接入。

四、可控性收益与代码成本

通用接入(SDK)的收益是「完全控制」,代价是「要写代码」:

选择 SDK 的典型场景
  ├─ 要精细控制召回什么、注入到哪
  ├─ 要自定义 sanitize(高敏感场景)
  ├─ 要特殊降级逻辑(如多记忆源容灾)
  ├─ Agent 是产品核心,要把记忆做深
  └─ 自研 Agent,本来就要写代码
​

💡 技巧:SDK 的「可控性」在产品级 Agent 里特别值钱。比如你想「按用户画像动态调整召回策略」(资深用户多召回、新手少召回),代理层做不到,SDK 你自己写就行。这种「记忆策略产品化」的需求,只有 SDK 能满足。

五、五类接入的总对比

把五类接入(本节是第五类)做个总对比,帮你为给定场景选型:

五类接入对比
  ┌─────────────┬──────────┬──────────┬──────────┐
  │ 接入方式     │ 接入成本  │ 可控程度  │ 适用      │
  ├─────────────┼──────────┼──────────┼──────────┤
  │ 代理层       │ 极低      │ 低        │ Claude Code等成熟产品 │
  │ Hermes适配器 │ 低        │ 中        │ Hermes长期常驻 │
  │ OpenClaw插件 │ 中        │ 中        │ OpenClaw框架 │
  │ SDK四步法    │ 中        │ 高        │ 自研/通用Agent │
  │ (本节通用)   │           │           │              │
  └─────────────┴──────────┴──────────┴──────────┘
  
  共同点:终点都是同一个记忆核心,接入方式可换,记忆能力统一
​

这就是第 10 章的总图景——五类框架、四条路径(代理/适配器/插件/SDK),但终点都是同一个记忆核心。无论你用哪个框架,都能找到对应的接入路径,共享同一套团队记忆。这是「记忆资产与 Agent 框架解耦」的最终体现——接入方式可选,记忆统一。

本节要点回顾

1. OpenAI 兼容普遍:事实标准,几乎覆盖所有自研 Agent 场景——通用接入覆盖面最广。
2. 用 SDK 四步法:能改源码的自研 Agent 用四步法(召回/捕获/工具/降级)。
3. 最小骨架:OpenAI 协议 + SDK,套骨架即可,任何兼容 Agent 通用。
4. 可控收益:完全控制召回/注入/sanitize/降级——产品级 Agent 把记忆做深的必要手段。
5. 五类总对比:代理(省心失控)/适配器(框架特化)/SDK(费心可控),终点都是同一记忆核心。

第 10 章到此完成——五类框架的接入路径都讲清了。下一章把所有能力汇成一套完整玩法——场景实战:组队、装配与 Loop 复利。