1. RD-Agent 启动报 litellm 元数据缺失先别急着重装RD-Agent 是微软开源的一个自动化研发智能体框架能自己读论文、写代码、跑实验、迭代模型适合做量化研究、算法调优这类需要反复试错的场景。它内部调用大模型时依赖 litellm 这个库来统一各家 API 的调用方式所以 litellm 装不好RD-Agent 连启动都过不去。你大概率遇到的是这个报错importlib.metadata.PackageNotFoundError: No package metadata was found for litellm或者更直白一点PackageNotFoundError: litellm这个报错的意思是Python 在当前的运行环境里通过importlib.metadata.version(litellm)去查 litellm 的版本号结果查不到任何元数据。注意它说的不是「litellm 没装」而是「元数据找不到」。这两件事有区别——包可能装了一半、装到了别的环境、或者装的时候元数据写坏了。我试过在一个 conda 环境里pip install litellm显示成功但 RD-Agent 一跑还是报这个错最后发现是 pip 装到了 base 环境而 RD-Agent 跑在另一个环境里。所以排查的第一步永远是确认你操作的环境和 RD-Agent 运行的环境是同一个。这篇会从依赖解析和包索引配置两个角度把这个问题拆开讲清楚。核心思路是先把 litellm 的元数据修好再把 pip 源和包索引指到稳定的地址最后用python -c验证元数据真的可读。整个过程你可以在本地完整复现。适合谁看正在本地或服务器上跑 RD-Agent、被 litellm 元数据报错卡住、想搞清楚 pip 依赖解析到底怎么回事的人。不需要你懂太多 Python 打包知识跟着命令走就行。先明确一个判断标准如果pip show litellm有输出但python -c import importlib.metadata; print(importlib.metadata.version(litellm))报错那就是元数据问题如果pip show litellm直接说没找到那就是根本没装到当前环境。两种情况处理方式不同下面分开说。2. 用 TaoToken 做依赖源与包索引的前置准备在动手修 litellm 之前先把「包从哪来」这件事定下来。很多人元数据反复出问题根源是 pip 源不稳定或者混用了多个索引导致同一个包被装了好几次、元数据互相覆盖。TaoToken 在这里的角色是提供一个统一的模型调用入口同时它的 API 地址可以作为你配置依赖和后续验证的基准。RD-Agent 跑起来之后要调大模型litellm 负责把请求发出去而请求发到哪个 Base URL、用哪个 Key、指定哪个 Model ID这三件套要提前准备好。你可以先到官网了解整体能力https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content然后进控制台创建 API Key这一步是后面配置 litellm 和 RD-Agent 的前提https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完 Key 之后去 API Keys 页面管理你的密钥注意别把 Key 直接提交到 githttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite如果你后面要接 Claude Code 或者做长期编码任务可以看下 Coding Plan 的说明它更适合持续性的 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档在这里配置 Base URL 和 Model ID 的细节以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 的基础地址是https://taotoken.net/api注意这个地址不加 UTM 参数配置到代码或环境变量里时用这个干净的地址。前置准备做完你手里应该有三样东西一个可用的 API Key、Base URLhttps://taotoken.net/api、以及你要用的 Model ID。这三样在后面的 litellm 配置里会直接用到。现在回到依赖问题。RD-Agent 的依赖里对 litellm 有版本要求一般要求1.73。如果你的 pip 源指向了一个同步不及时的镜像可能拉到的是旧版本旧版本的元数据格式和新版 Python 的importlib.metadata不兼容就会报 PackageNotFoundError。所以把 pip 源固定到一个稳定地址是预防这类问题的关键一步。3. 可复制的 pip 源与 litellm 版本锁定配置这一节给你可以直接复制的配置片段。先确认你在正确的环境里然后按顺序操作。第一步激活 RD-Agent 所在的环境。如果你用 condaconda activate rdagent如果你用 venvsource /path/to/your/venv/bin/activate激活后确认 Python 路径这一步很重要能避免装错环境which python python --version第二步配置 pip 源。你可以临时指定索引地址也可以写进配置文件。临时指定适合一次性安装pip install litellm1.73 \ --index-url https://pypi.org/simple \ --force-reinstall \ --no-cache-dir如果你所在网络访问默认源较慢可以换成你本地可用的镜像源但要注意镜像同步延迟。写进配置文件的方式更持久Linux/macOS 下编辑~/.pip/pip.confWindows 下编辑%APPDATA%\pip\pip.ini[global] index-url https://pypi.org/simple timeout 60如果你需要额外索引可以这样写[global] index-url https://pypi.org/simple extra-index-url https://your-mirror.example.com/simple timeout 60注意extra-index-url不要随便加多个索引混用容易导致依赖解析混乱同一个包从不同源拉到不同版本元数据就可能对不上。第三步锁定 litellm 版本。RD-Agent 要求1.73但为了避免自动升级到不兼容的新版本建议锁一个具体版本。先看当前装了什么pip show litellm如果没装或者版本低强制重装一个明确版本pip install litellm1.73.0 --force-reinstall --no-cache-dir--force-reinstall会覆盖已有安装--no-cache-dir避免用到本地缓存的坏包。这两个参数组合是修元数据问题的常用手段。第四步如果你用 requirements 管理依赖可以在文件里写死litellm1.73.0然后pip install -r requirements.txt --force-reinstall --no-cache-dir第五步配置 litellm 调用 TaoToken。litellm 支持通过环境变量或代码配置。环境变量方式export OPENAI_API_KEY你的_TaoToken_Key export OPENAI_API_BASEhttps://taotoken.net/api如果你在代码里配置可以这样写import litellm response litellm.completion( model你的_Model_ID, messages[{role: user, content: hello}], api_key你的_TaoToken_Key, api_basehttps://taotoken.net/api ) print(response)这里的三件套对应关系是Base URL 用https://taotoken.net/apiKey 用你在控制台创建的Model ID 用文档里列出的可用模型标识。三者缺一不可写错任何一个都会在调用阶段报错而不是在元数据阶段。第六步如果你用 Claude Code 或类似工具配置方式略有不同参考文档里的 ClaudeCodeAnthropic 部分https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite配置完成后先别急着跑 RD-Agent下一节先验证元数据是否真的可读。4. 用 python -c 验证 litellm 元数据可读性装完之后必须验证不然你只是「以为」修好了。验证分三层包能不能导入、元数据能不能读到、版本号对不对。第一层验证导入python -c import litellm; print(import ok)如果这行就报错说明包根本没装到当前环境回到上一节检查环境激活和 pip 路径。第二层验证元数据可读这是直接对应报错的那一行python -c import importlib.metadata; print(importlib.metadata.version(litellm))成功的话会输出类似1.73.0如果这行报PackageNotFoundError说明元数据还是坏的。这时候可以试试重新生成元数据pip install --force-reinstall --no-cache-dir litellm第三层验证 litellm 自己报告的版本python -c import litellm; print(litellm.version)注意litellm.version和importlib.metadata.version(litellm)是两个不同的来源前者是包内部定义的后者是安装时写入的元数据。两个都能读到且一致才算真正修好。第四层验证 RD-Agent 能启动rdagent --version正常会输出版本号比如0.7.0。如果这一步还报 litellm 元数据错误说明 RD-Agent 用的 Python 解释器和你刚才操作的不是同一个。用这个命令确认 RD-Agent 到底用的哪个 Pythonhead -1 $(which rdagent)输出的路径就是它实际使用的解释器然后针对那个解释器重新装 litellm。第五层做一次真实的模型调用验证确认三件套配置正确python -c import litellm resp litellm.completion( model你的_Model_ID, messages[{role:user,content:ping}], api_key你的_TaoToken_Key, api_basehttps://taotoken.net/api ) print(resp.choices[0].message.content) 如果这行能打印出模型返回的内容说明从依赖到调用整条链路都通了。如果报 401那是 Key 的问题如果报连接错误那是 Base URL 的问题如果报 model not found那是 Model ID 的问题。这三种错误和元数据错误是不同层面的别混在一起排查。验证通过后再跑 RD-Agent 的完整流程rdagent --debug--debug会输出详细日志方便你在出问题时定位到具体是哪一步。5. 本篇常见报错排查对照这一节把你会遇到的报错和对应处理列清楚方便对照。报错一PackageNotFoundError: No package metadata was found for litellm这是本篇的核心报错。原因通常是 litellm 没装到当前环境或者元数据损坏。处理pip install litellm1.73 --force-reinstall --no-cache-dir python -c import importlib.metadata; print(importlib.metadata.version(litellm))如果还不行检查是不是装到了别的环境pip show litellm | grep Location python -c import sys; print(sys.executable)两个路径对不上就是环境错了。报错二401 Unauthorized或AuthenticationError这不是元数据问题是 Key 的问题。检查你的 API Key 是否正确、是否过期、是否有多余空格。确认 Key 来自https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite报错三local proxy failed或连接超时检查 Base URL 是否写成https://taotoken.net/api注意不要多加路径或斜杠。如果你在代码里同时设置了OPENAI_API_BASE和api_base参数以参数为准确认没有互相覆盖。报错四Error reading choices或返回结构解析失败这通常是模型返回了非预期格式或者 Model ID 写错了导致路由到了不支持的模型。确认 Model ID 和文档一致https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite报错五OAuth相关错误如果你用的是 Claude Code 类工具OAuth 流程和普通 API Key 不同。参考 ClaudeCodeAnthropic 的配置说明确认认证方式选对了。报错六依赖冲突pipdeptree显示多个版本装个 pipdeptree 看依赖树pip install pipdeptree pipdeptree | grep litellm如果 litellm 被多个包以不同版本要求用pip install litellm1.73.0强制统一然后重装冲突的包。报错七Python 版本过低importlib.metadata在 Python 3.8 才进标准库。如果你用 3.7 或更低需要装 backportpip install importlib_metadata然后代码里把importlib.metadata改成importlib_metadata。不过更推荐直接升级到 Python 3.10RD-Agent 官方也推荐 3.10。报错八conda 环境混乱如果上面都试过还不行干脆重建环境conda remove -n rdagent --all conda create -n rdagent python3.10 -y conda activate rdagent pip install rdagent重建后重新配置 litellm 和 TaoToken 三件套。排查的核心逻辑是先分清是「装的问题」还是「配置的问题」。元数据报错属于装的问题401 和连接错误属于配置的问题。分清楚之后处理路径就清晰了。6. 把依赖修好之后RD-Agent 的下一步litellm 元数据修好只是让 RD-Agent 能启动真正跑起来还需要模型调用链路通畅。这时候你手里的三件套——Base URL、Key、Model ID——就是关键。如果你只是想让 RD-Agent 跑通一次实验用 API Keys 配合接入文档就够了https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你想先单独验证模型能不能正常对话不跑 RD-Agent 的完整流程可以用模型对话页面快速测一下https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算长期用 RD-Agent 做自动化研发或者接 Claude Code 做持续编码Coding Plan 更适合这种高频、长时间的 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后说一个实际经验RD-Agent 这类框架的依赖问题八成出在环境隔离上。你在一台机器上可能有 base、rdagent、还有别的项目环境pip 装的时候不指定环境很容易装错。养成习惯每次装包前先which python和pip show确认位置能省掉大量排查时间。元数据报错看着吓人本质就是「包和元数据没对上」把环境对齐、版本锁死、源固定问题就解决了。