RuntimeError: SENTINEL: transformers was imported

快速结论：该报错发生在导入 langchain_core.language_models.BaseChatModel 时，因为顶层无条件导入了 transformers，导致额外增加 300-500ms 的启动时间。优先排查你的代码中是否实际使用了 GPT-2 回退分词器，并确认是否已升级到包含懒加载修复的版本。

适用环境：Issue 中确认涉及的包为 langchain-core；触发场景为任意导入 BaseChatModel 的 Python 项目。Issue 未提供具体的 Python、操作系统、CUDA 或显卡信息，未验证的环境信息不在此列出。

最快修复方案：升级到包含 PR #38037 的 langchain-core 版本，该提交将 from transformers import GPT2TokenizerFast 移入 get_tokenizer() 函数体内，实现懒加载。Issue 中没有提供其他已验证的一步修复命令。

注意事项：懒加载后，只有首次实际调用 get_tokenizer()（即真正需要 GPT-2 回退分词器时）才会触发 transformers 导入；如果你确实需要该功能，首次调用的耗时不会减少，只是从“导入期”转移到了“调用期”。

问题场景

用户在使用 LangChain 框架时，仅执行 from langchain_core.language_models import BaseChatModel 这一导入操作，未实例化任何 HuggingFace 模型或调用分词器，却触发了 transformers 库的完整加载，导致应用/服务冷启动时间显著增加。Issue 中多位用户反馈，这影响 Lambda、serverless 环境和 CLI 工具的启动性能。

报错原文

RuntimeError: SENTINEL: transformers was imported
import time:       158 |        158 |       transformers.dependency_versions_table
import time:       293 |        293 |             transformers.utils.doc
import time:     296533 |     298007 |               transformers.utils.import_utils
import time:    367927 |     851828 |   transformers
import time:      1698 |       5805 |     transformers.integrations.ggml
import time:       757 |     709222 |     transformers.modeling_gguf_pytorch_utils
import time:       554 |     716357 |   transformers.tokenization_utils_tokenizers

原因分析

根本原因已由维护者确认：langchain_core/language_models/base.py 文件顶部存在无条件导入语句 from transformers import GPT2TokenizerFast。这导致只要导入 BaseChatModel，就会连带加载整个 transformers 库（约增加 300-500ms），即使用户从未使用这个 GPT-2 回退分词器。这是 langchain-core 的性能问题，属于无条件导入外部依赖的典型反模式。

环境排查

langchain-core 版本：确认是否已升级到包含 PR #38037（提交 cccfbb1c5）的版本，该版本将导入移入 get_tokenizer() 函数内部。
transformers 安装状态：确认环境中是否安装了 transformers；即使已安装，也建议验证是否真的需要它（即是否使用 GPT-2 回退分词器）。
实际调用链：检查代码中是否调用了 get_tokenizer() 或 get_num_tokens 等相关方法，这些调用才会触发分词器加载。

解决步骤

升级 langchain-core：将 langchain-core 升级到包含 PR #38037 的最新稳定版本，该 PR 已将 transformers 导入移入 get_tokenizer() 函数体内部（该函数已有 @functools.cache 装饰器），实现懒加载。
验证导入是否仍触发 transformers：如果升级后问题依旧，检查是否有其他导入路径或第三方包在导入 langchain-core 时间接导入了 transformers；可使用 Issue 中提供的 sentinel 验证方法（构造一个导入即报错的 transformers.py 模块放在 sys.path 最前面，然后导入 BaseChatModel，确认不再触发 sentinel）。
评估替代方案（可优先尝试）：如果暂时无法升级，且确定不需要 GPT-2 回退分词器，可在项目中完全避免调用相关回退逻辑，或参考 Issue 评论中的懒加载模式，自行封装延迟导入。
贡献修复（可选）：如果你有维护权限或愿意贡献代码，可以参考 Issue 中提到的多个 PR（#36868、#36934、#37321、#37446），核心改动均为将导入语句移入 get_tokenizer() 函数体内。

验证方法

升级后，重新执行原本触发问题的导入操作，使用 Python 的导入计时或 sentinel 模块方式确认 transformers 不再被无条件加载。具体来说：创建一个包含 raise RuntimeError("SENTINEL: transformers was imported") 的 transformers.py 文件并置于 sys.path 最前，然后导入 BaseChatModel，如不触发报错即说明修复生效；仅在调用 get_tokenizer() 时才应触发该报错。