用 llama_index 跑旧脚本报 GradientBaseModelLLM

直接给结论，这是典型的 LlamaIndex 版本大升级导致的 API 路径变更。如果你在运行几年前的旧代码，直接用 from llama_index.llms import GradientBaseLLM 几乎肯定会崩，因为现在的 LlamaIndex 已经把具体的 LLM 实现拆分到了独立的集成包里，不再全部堆在主库的 llms 目录下。

为什么会报这个 ImportError

报错信息很明确：ImportError: cannot import name 'GradientBaseModelLLM' from 'llama_index.llms'。

这种情况通常发生在尝试运行一个基于旧版本 LlamaIndex 编写的脚本时。在早期的版本中，很多模型类是直接定义在 llama_index.llms 下的，但随着框架演进，为了精简核心库，官方把各种第三方模型的对接全部移到了 llama-index-llms-xxx 这种独立的插件包中。所以当你尝试从旧路径导入时，Python 找不到这个类，直接抛出导入错误。

怎么排查和修复

要解决这个问题，不能只改代码，得先对齐依赖包。

一、检查并安装对应的集成包
现在的 LlamaIndex 要求你安装具体的模型集成包。既然你要用 Gradient，得先安装 llama-index-llms-gradient。

pip install llama-index-llms-gradient

二、修改导入路径
安装完之后，不要再去 llama_index.llms 里面找了，直接从具体的集成包路径导入。

把原来的：

from llama_index.llms import GradientBaseLLM

修改为：

from llama_index.llms.gradient import GradientLLM

（注意：这里类名可能在更新中从 GradientBaseLLM 变更为 GradientLLM，具体取决于你安装的集成包版本，建议在 IDE 里用自动补全确认一下）。

三、验证版本兼容性
如果你发现改了导入路径还是报错，大概率是脚本里其他部分也用了过时的 API。你可以通过以下命令确认当前的 LlamaIndex 版本：

pip show llama-index

如果脚本实在太旧（比如两三年前的），而你又不想大规模重构代码，最暴力的办法是把 llama-index 降级到脚本编写时的那个版本，但这通常不推荐，因为你会错过很多性能优化和新功能。

避坑总结

这次踩坑让我意识到，LlamaIndex 的更新频率极高，且破坏性更新（Breaking Changes）很多。如果你接手的是别人的旧项目，第一件事不要急着 pip install -r requirements.txt 然后直接运行，建议先对照最新的文档检查 llms 和 embeddings 的导入路径。

现在所有的第三方模型导入逻辑基本都统一成了 from llama_index.llms.xxx import XxxLLM 这种模式。只要看到 ImportError: cannot import name... from 'llama_index.llms'，第一反应就应该是：这个模型被移到独立的集成包里了。