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 官方包强制要求 numpy2.0.0, 和HelloAgents 主依赖版本存在冲突,因此需要单独安装 pip install numpy1.26.4 bfcl-eval第二条命令是必做步骤文档明确说明了原因bfcl-eval强制要求numpy2.0.0与 HelloAgents 主依赖版本冲突所以要固定numpy1.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 bfcl12.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 KeyHelloAgentsLLM需要调用模型接口# OpenAI API Key用于GPT-4o export OPENAI_API_KEYyour_openai_api_keyexport 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(nameTestAgent, llmllm) # 2. 创建BFCL评估工具 bfcl_tool BFCLEvaluationTool() # 3. 运行评估自动完成所有步骤 results bfcl_tool.run( agentagent, categorysimple_python, # 评估类别 max_samples5 # 评估样本数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样本数默认 50 表示全部、--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如果需要自定义评估流程比如换提示词、改提取逻辑用底层组件文档方式 3code/chapter12/03_bfcl_custom_evaluation.py 展示了完整流程from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.evaluation import BFCLDataset, BFCLEvaluator # 1. 创建智能体 llm HelloAgentsLLM() agent SimpleAgent(nameTestAgent, llmllm) # 2. 加载数据集 dataset BFCLDataset( bfcl_data_dir./temp_gorilla/berkeley-function-call-leaderboard/bfcl_eval/data, categorysimple_python ) data dataset.load() # 3. 创建评估器 evaluator BFCLEvaluator( datasetdataset, categorysimple_python, evaluation_modeast # 使用AST匹配模式 ) # 4. 运行评估 results evaluator.evaluate(agent, max_samples10) # 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 匹配而非字符串匹配函数名必须精确一致参数键值对集合相等忽略顺序参数值语义等价如23等价于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, categorycategory, max_samples10) 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），仅供参考