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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=然后进控制台创建 API Key，这一步是后面配置 litellm 和 RD-Agent 的前提：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite创建完 Key 之后，去 API Keys 页面管理你的密钥，注意别把 Key 直接提交到 git：
https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite如果你后面要接 Claude Code 或者做长期编码任务，可以看下 Coding Plan 的说明，它更适合持续性的 Agent 场景：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite接入文档在这里，配置 Base URL 和 Model ID 的细节以文档为准：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewriteAPI 的基础地址是：
https://taotoken.net/api注意这个地址不加 UTM 参数，配置到代码或环境变量里时用这个干净的地址。
前置准备做完，你手里应该有三样东西：一个可用的 API Key、Base URL（https://taotoken.net/api）、以及你要用的 Model ID。这三样在后面的 litellm 配置里会直接用到。
现在回到依赖问题。RD-Agent 的依赖里对 litellm 有版本要求，一般要求>=1.73。如果你的 pip 源指向了一个同步不及时的镜像，可能拉到的是旧版本，旧版本的元数据格式和新版 Python 的importlib.metadata不兼容，就会报 PackageNotFoundError。所以把 pip 源固定到一个稳定地址，是预防这类问题的关键一步。
3. 可复制的 pip 源与 litellm 版本锁定配置
这一节给你可以直接复制的配置片段。先确认你在正确的环境里，然后按顺序操作。
第一步，激活 RD-Agent 所在的环境。如果你用 conda：
conda activate rdagent如果你用 venv：
source /path/to/your/venv/bin/activate激活后确认 Python 路径，这一步很重要，能避免装错环境：
which python python --version第二步，配置 pip 源。你可以临时指定索引地址，也可以写进配置文件。临时指定适合一次性安装：
pip install "litellm>=1.73" \ --index-url https://pypi.org/simple \ --force-reinstall \ --no-cache-dir如果你所在网络访问默认源较慢，可以换成你本地可用的镜像源，但要注意镜像同步延迟。写进配置文件的方式更持久，Linux/macOS 下编辑~/.pip/pip.conf，Windows 下编辑%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 "litellm==1.73.0" --force-reinstall --no-cache-dir--force-reinstall会覆盖已有安装，--no-cache-dir避免用到本地缓存的坏包。这两个参数组合是修元数据问题的常用手段。
第四步，如果你用 requirements 管理依赖，可以在文件里写死：
litellm==1.73.0然后：
pip install -r requirements.txt --force-reinstall --no-cache-dir第五步，配置 litellm 调用 TaoToken。litellm 支持通过环境变量或代码配置。环境变量方式：
export OPENAI_API_KEY="你的_TaoToken_Key" export OPENAI_API_BASE="https://taotoken.net/api"如果你在代码里配置，可以这样写：
import litellm response = litellm.completion( model="你的_Model_ID", messages=[{"role": "user", "content": "hello"}], api_key="你的_TaoToken_Key", api_base="https://taotoken.net/api" ) print(response)这里的三件套对应关系是：Base URL 用https://taotoken.net/api，Key 用你在控制台创建的，Model ID 用文档里列出的可用模型标识。三者缺一不可，写错任何一个都会在调用阶段报错，而不是在元数据阶段。
第六步，如果你用 Claude Code 或类似工具，配置方式略有不同，参考文档里的 ClaudeCodeAnthropic 部分：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite配置完成后，先别急着跑 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 到底用的哪个 Python：
head -1 $(which rdagent)输出的路径就是它实际使用的解释器，然后针对那个解释器重新装 litellm。
第五层，做一次真实的模型调用验证，确认三件套配置正确：
python -c " import litellm resp = litellm.completion( model='你的_Model_ID', messages=[{'role':'user','content':'ping'}], api_key='你的_TaoToken_Key', api_base='https://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 "litellm>=1.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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite报错三：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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite报错五：OAuth相关错误
如果你用的是 Claude Code 类工具，OAuth 流程和普通 API Key 不同。参考 ClaudeCodeAnthropic 的配置说明，确认认证方式选对了。
报错六：依赖冲突，pipdeptree显示多个版本
装个 pipdeptree 看依赖树：
pip install pipdeptree pipdeptree | grep litellm如果 litellm 被多个包以不同版本要求，用pip install "litellm==1.73.0"强制统一，然后重装冲突的包。
报错七：Python 版本过低
importlib.metadata在 Python 3.8 才进标准库。如果你用 3.7 或更低，需要装 backport：
pip install importlib_metadata然后代码里把importlib.metadata改成importlib_metadata。不过更推荐直接升级到 Python 3.10，RD-Agent 官方也推荐 3.10。
报错八：conda 环境混乱
如果上面都试过还不行，干脆重建环境：
conda remove -n rdagent --all conda create -n rdagent python=3.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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite如果你想先单独验证模型能不能正常对话，不跑 RD-Agent 的完整流程，可以用模型对话页面快速测一下：
https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=如果你打算长期用 RD-Agent 做自动化研发，或者接 Claude Code 做持续编码，Coding Plan 更适合这种高频、长时间的 Agent 场景：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite最后说一个实际经验：RD-Agent 这类框架的依赖问题，八成出在环境隔离上。你在一台机器上可能有 base、rdagent、还有别的项目环境，pip 装的时候不指定环境，很容易装错。养成习惯，每次装包前先which python和pip show确认位置，能省掉大量排查时间。元数据报错看着吓人，本质就是「包和元数据没对上」，把环境对齐、版本锁死、源固定，问题就解决了。
