跳转到内容
AI Agent 教程 AI Agent 教程

公共 API 稳定性策略：向后兼容与弃用流程

公共 API 稳定性策略：向后兼容与弃用流程

学习目标

本章要解决什么问题：拥有数百万用户的框架如何在持续迭代的同时不破坏现有代码？

读者将学到：

  • LangChain 的公共 API 边界定义
  • 弃用警告的三级机制（DeprecationWarning / PendingDeprecationWarning / BetaWarning）
  • 函数签名兼容与参数迁移的实践

前置知识

本章是 LangChain 特有的工程实践，不涉及通用知识原理。

项目实践

公共 API 的边界

LangChain 将公共 API 定义为：

  • init_chat_model() — 统一的模型初始化入口
  • create_agent() — Agent 创建的公共接口
  • 中间件装饰器（@before_model、@wrap_model_call 等）
  • Partner 包的导出类（如 ChatOpenAI）

内部实现（以 _ 开头的模块和函数）不保证稳定性。例如 _ConfigurableModel 是内部类，用户不应直接实例化。

弃用警告的三级机制

LangChain 使用三层弃用警告，给用户不同的提前期：

级别警告类含义提前期
PendingLangChainPendingDeprecationWarning即将弃用，下次主版本移除1-2 个主版本
DeprecationLangChainDeprecationWarning已弃用，但仍可用当前主版本内有效
BetaLangChainBetaWarningBeta 功能，可能变更无保证

实际示例：init_chat_model() 中推断 google_vertexai provider 时的弃用警告：

# 伪代码
warnings.warn(
    f"Inferred `model_provider='google_vertexai'` from {model_name!r}. "
    "This default will change to 'google_genai' in the next major release."
    "To keep current behavior, pass `model_provider='google_vertexai'`.",
    DeprecationWarning,
    stacklevel=5,
)

设计要点：stacklevel=5 确保警告指向用户调用的位置，而非框架内部代码。

参数迁移：system_prompt → system_message

函数签名变更是最常见的破坏性变更。LangChain 的迁移策略：

# 伪代码：接受旧参数名，内部转换为新参数
def init_chat_model(
    model: str,
    model_provider: str | None = None,
    system_message: str | None = None,
    # 旧参数名保留，内部映射
    system_prompt: str | None = None,
) -> Runnable:
    if system_prompt is not None:
        warnings.warn(
            "system_prompt is deprecated, use system_message instead.",
            DeprecationWarning,
        )
        if system_message is not None:
            raise ValueError("Cannot specify both system_message and system_prompt")
        system_message = system_prompt

CI 中的弃用警告过滤

测试配置中明确过滤弃用警告，避免测试输出被淹没：

pyproject.toml
[tool.pytest.ini_options]
filterwarnings = [
    "ignore::langchain_core._api.beta_decorator.LangChainBetaWarning",
    "ignore::langchain_core._api.deprecation.LangChainDeprecationWarning:tests",
    "ignore::langchain_core._api.deprecation.LangChainPendingDeprecationWarning:tests",
]

设计要点：只在 tests 模块中忽略这些警告，用户代码仍会正常显示。

经典包的兼容层

libs/langchain/（旧版，PyPI 名 langchain-classic）作为兼容层保留，无新功能。用户从旧版迁移时，代码不会立即失效：

libs/langchain/        → langchain-classic（遗留，无新功能）
libs/langchain_v1/     → langchain（活跃开发，v1.x）

问题与规避

弃用警告淹没正常输出

问题：用户使用旧 API 时，大量弃用警告干扰正常输出。

对策：用户可通过 warnings.filterwarnings("ignore", category=LangChainDeprecationWarning) 全局关闭。CI 中已在测试配置中过滤。

迁移窗口过短

问题：用户可能没有及时跟随弃用警告迁移。

对策：Pending → Deprecation → 移除的三段式流程，给用户至少 1-2 个主版本的时间。经典包（langchain-classic）作为最后的安全网保留兼容。

设计取舍

运行时警告 vs 编译时错误

方案优势代价
运行时警告用户有充足迁移时间、渐进式升级运行时开销、警告可能被忽略
立即报错用户立即知道需要修改、不产生技术债破坏所有现有代码、用户信任下降

LangChain 选择运行时警告，因为框架用户代码量大，立即报错会导致升级阻力过大。

参数兼容 vs 严格签名

方案优势代价
保留旧参数名旧代码继续工作、用户有迁移时间函数签名膨胀、维护负担
严格签名函数签名简洁立即破坏所有调用旧参数的代码

LangChain 选择保留旧参数名并内部映射，在函数体内处理兼容逻辑。这增加了函数体复杂度，但保证了向后兼容。

参考来源

版本信息

📅 2026-05-26 🏷️ 33875fd 🔀 33875fd

标签

api-stabilitydeprecationbackward-compatwarnings