HelloAgents 如何安装 BFCL 评估工具并评估智能体的工具调用能力？-开发者社区

HelloAgents 如何安装 BFCL 评估工具并评估智能体的工具调用能力？

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

如果你在优化 HelloAgents 中的智能体提示词或更换 LLM 后，想客观地知道它的函数调用（工具调用）能力有没有变好，可以用第十二章的 BFCL 评估模块。本文对应 docs/chapter12/第十二章智能体性能评估.md 的 12.2 节与 code/chapter12 配套示例：先安装hello-agents[evaluation]与 BFCL 官方评估包，克隆官方数据集，然后运行一键评估，拿到准确率、BFCL 格式结果文件和 Markdown 评估报告。评估结果由 AST 匹配算法判定，官方评估模式下结果与 BFCL 排行榜的计算方式一致。

准备环境：安装框架与 BFCL 评估包

文档给出的安装步骤（12.1.4 节）：

# 安装HelloAgents框架（第12章版本） pip install "hello-agents[evaluation]==0.2.7" # 由于 `bfcl-eval` 官方包强制要求 numpy<=2.0.0, 和HelloAgents 主依赖版本存在冲突,因此需要单独安装 pip install "numpy==1.26.4" bfcl-eval

第二条命令是必做步骤，文档明确说明了原因：bfcl-eval强制要求numpy<=2.0.0，与 HelloAgents 主依赖版本冲突，所以要固定numpy==1.26.4再装bfcl-eval。

两处版本与包名的差异需要注意：

章节文档写的是hello-agents[evaluation]==0.2.7，而 code/chapter12/README.md 的环境准备一节写的是pip install hello-agents[evaluation]==0.2.3。本文以章节文档的 0.2.7 为准，如果安装时该版本不可用，再参考代码目录 README 的版本号。
12.2.1 节在"BFCL 官方评估工具"小标题下写的是pip install bfcl，12.1.4 节和 code/chapter12/04_run_bfcl_evaluation.py 的报错提示（pip install bfcl-eval）使用的包名是bfcl-eval。两个命令提供的是同一个bfclCLI，按 12.1.4 的完整命令安装即可。

另外，code/chapter12/README.md 的环境准备中还要求为 LLM 配置 API Key（HelloAgentsLLM需要调用模型接口）：

# OpenAI API Key（用于GPT-4o） export OPENAI_API_KEY="your_openai_api_key"

export HF_TOKEN=...那一行文档注明是"用于GAIA数据集"，BFCL 评估走本地克隆的数据，不需要 HuggingFace Token，可以跳过。

获取 BFCL 数据集

BFCL 数据集随官方 gorilla 仓库分发，推荐直接克隆（12.2.2 节"方法 1"）。在工作目录下执行：

# 克隆BFCL仓库 git clone https://github.com/ShishirPatil/gorilla.git temp_gorilla cd temp_gorilla/berkeley-function-call-leaderboard # 查看BFCL v4数据集 ls bfcl_eval/data/ # 输出: BFCL_v4_simple_python.json BFCL_v4_multiple.json BFCL_v4_parallel.json ... # 查看ground truth ls bfcl_eval/data/possible_answer/ # 输出: BFCL_v4_simple_python.json BFCL_v4_multiple.json ...

文档给出选择这种方式的理由：包含完整的 ground truth（标准答案），数据格式与官方评估工具完全一致，可以直接使用官方评估脚本，并支持 BFCL v4 最新版本。ls能看到BFCL_v4_simple_python.json等文件，即说明数据集准备完成。评估类别可以在BFCL_v4_simple_python、BFCL_v4_multiple、BFCL_v4_parallel等文件中看到，对应文档表 12.2 列出的四个难度类别（simple、multiple、parallel、irrelevance）。

数据目录的约定路径是./temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data，后续所有示例都使用这个相对路径。

主路径：用 BFCLEvaluationTool 一键评估

code/chapter12/02_bfcl_quick_start.py 是文档"方式 1"的配套脚本，完整内容就是下面这段，在数据集所在的目录中直接运行python 02_bfcl_quick_start.py即可（也可以把它作为示例代码粘贴到自己的工作目录运行）：

from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import BFCLEvaluationTool # 1. 创建要评估的智能体 llm = HelloAgentsLLM() agent = SimpleAgent(name="TestAgent", llm=llm) # 2. 创建BFCL评估工具 bfcl_tool = BFCLEvaluationTool() # 3. 运行评估（自动完成所有步骤） results = bfcl_tool.run( agent=agent, category="simple_python", # 评估类别 max_samples=5 # 评估样本数（0表示全部） ) # 4. 查看结果 print(f"准确率: {results['overall_accuracy']:.2%}") print(f"正确数: {results['correct_samples']}/{results['total_samples']}")

参数说明：

category：评估类别，simple_python是最基础的单函数调用类别，适合先跑通流程；
max_samples：评估样本数，设为0表示全部样本（simple_python类别共 400 个样本）；
run_official_eval：默认为True，即评估后自动运行 BFCL 官方评估；model_name可选，用于官方评估中的模型名。

这个工具会自动完成四个步骤（12.2.4 节）：加载数据集并运行 HelloAgents 评估、把结果导出为 BFCL 格式保存到evaluation_results/bfcl_official/、把结果文件复制到result/{model_name}/目录后运行bfcl evaluate --model ... --test-category ... --partial-eval官方命令、生成 Markdown 评估报告。

运行输出与结果验证

文档给出的运行输出示例如下（文档示例，你的准确率会随模型和样本不同而变化）：

============================================================ BFCL一键评估 ============================================================ 配置: 评估类别: simple_python 样本数量: 5 智能体: TestAgent ============================================================ 步骤1: 运行HelloAgents评估 ============================================================ ✅ BFCL数据集加载完成 数据目录: ./temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data 类别: simple_python 样本数: 400 Ground truth数: 400 🔧 开始 BFCL 评估... 进度: 1/5 进度: 5/5 ✅ BFCL 评估完成 总体准确率: 100.00% simple_python: 100.00% (5/5) ============================================================ 步骤3: 运行BFCL官方评估 ============================================================ 📊 评估结果汇总: Model,Overall Acc,simple_python Qwen/Qwen3-8B,100.00,100.00 ============================================================ 步骤4: 生成评估报告 ============================================================ 📄 报告已生成: ./evaluation_reports/bfcl_report_20251011_005938.md

判断评估是否完成，看三处：

终端出现"✅ BFCL数据集加载完成"并显示"样本数"与"Ground truth数"，说明数据集路径正确（示例中为 400/400）；
出现"📊 评估结果汇总"表格和"准确率"数值，这是官方评估的结果；
./evaluation_reports/下生成了bfcl_report_*.md报告，内容包含评估概览、分类准确率、逐样本详情（问题、预测、标准答案、是否正确）和准确率可视化。

02_bfcl_quick_start.py 末尾的运行输出示例同样是准确率: 100.00%、正确数: 5/5，这也是文档示例，不代表固定预期。

可选路径：命令行脚本与自定义评估

命令行一键脚本

适合批量评估或集成到 CI/CD 流程（文档"方式 2"），对应 code/chapter12/04_run_bfcl_evaluation.py。文档给出的调用方式：

python chapter12/04_run_bfcl_evaluation.py --category simple_python --samples 10 # 指定模型名称（用于BFCL官方评估） python examples/04_run_bfcl_evaluation.py \ --category simple_python \ --samples 10 \ --model-name "Qwen/Qwen3-8B"

仓库内该脚本位于code/chapter12/下，按实际放置位置调整路径即可。三个参数：--category评估类别（默认 simple_python）、--samples样本数（默认 5，0 表示全部）、--model-name模型名称（默认 Qwen/Qwen3-8B，需是 BFCL 支持的模型，可运行bfcl models查看）。

脚本的执行顺序是：检查数据目录 → 运行 HelloAgents 评估 → 导出 BFCL 格式到evaluation_results/bfcl_official/→ 复制到result/{model_name}/→ 调用bfcl evaluate官方评估 → 展示结果。两个可用于判断的失败信号都写在脚本里：

若 BFCL 数据目录不存在，脚本会打印"❌ BFCL数据目录不存在"并给出git clone --depth 1 https://github.com/ShishirPatil/gorilla.git temp_gorilla提示后退出，此时先完成上一节的数据集克隆；
若找不到bfcl命令，提示"请先安装: pip install bfcl-eval"。

脚本最后的"展示评估结果"步骤读取score/data_non_live.csv和score/{model_name}/non_live/BFCL_v4_{category}_score.json，这两个文件由 BFCL 官方评估生成，可以在其中看到最终准确率。

直接用 BFCLDataset 与 BFCLEvaluator

如果需要自定义评估流程（比如换提示词、改提取逻辑），用底层组件（文档"方式 3"），code/chapter12/03_bfcl_custom_evaluation.py 展示了完整流程：

from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.evaluation import BFCLDataset, BFCLEvaluator # 1. 创建智能体 llm = HelloAgentsLLM() agent = SimpleAgent(name="TestAgent", llm=llm) # 2. 加载数据集 dataset = BFCLDataset( bfcl_data_dir="./temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data", category="simple_python" ) data = dataset.load() # 3. 创建评估器 evaluator = BFCLEvaluator( dataset=dataset, category="simple_python", evaluation_mode="ast" # 使用AST匹配模式 ) # 4. 运行评估 results = evaluator.evaluate(agent, max_samples=10) # 5. 查看结果 print(f"准确率: {results['overall_accuracy']:.2%}") print(f"正确数: {results['correct_samples']}/{results['total_samples']}") # 6. 导出BFCL格式结果（可选） evaluator.export_to_bfcl_format( results, output_path="./evaluation_results/my_results.json" )

BFCLDataset的加载逻辑是：优先从本地bfcl_eval/data/加载测试数据，从bfcl_eval/data/possible_answer/加载 ground truth 并自动合并；找不到本地数据时才尝试从 Hugging Face 加载。想确认可用类别，可以调用dataset.get_available_categories()，文档示例输出为['simple_python', 'simple_java', 'simple_javascript', 'multiple', ...]。

指标含义与评估限制

BFCL 使用 AST 匹配而非字符串匹配：函数名必须精确一致，参数键值对集合相等（忽略顺序），参数值语义等价（如2+3等价于5）。核心指标是准确率（Accuracy），即 AST 匹配成功的样本比例，文档解释：Accuracy = 1.0表示全部正确，Accuracy = 0.8表示 80% 正确。分词匹配、参数校验都遵循这个规则，所以报告里逐样本的"是否正确"列可以直接用来定位薄弱环节。

需要注意文档 12.2.6 节明确说明的局限：

当前示例基于 SimpleAgent，它使用自定义工具调用格式[TOOL_CALL:tool_name:parameters]，需要 LLM 主动学习和使用该格式，复杂场景下表现可能不如使用原生函数调用的智能体；
示例主要验证了simple_python等基础类别，multiple、parallel、irrelevance等更复杂的类别还需要针对性优化；
评估成本主要来自 LLM API 调用，code/chapter12/README.md 估算 BFCL 每样本约 1 次 API 调用，完整评估 400 个样本约 4–8 元。

下一步：渐进式与多类别评估

文档 12.2.6 节给出的实践路径：先小样本快速测试（5 个样本），准确率超过 0.8 再扩到 50 个样本，仍超过 0.8 再跑全部样本；随后对simple_python、multiple、parallel、irrelevance逐类别评估并分析失败案例：

# 多类别评估 categories = ["simple_python", "multiple", "parallel", "irrelevance"] for category in categories: print(f"\n评估类别: {category}") results = bfcl_tool.run(agent, category=category, max_samples=10) print(f"准确率: {results['overall_accuracy']:.2%}")

如果需要禁用自动官方评估、手动控制bfcl evaluate调用或手动生成报告（bfcl_tool.generate_report），见第十二章 12.2.4 节。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考