Upsonic 基准测试环境搭建与运行指南虚拟环境、依赖安装、.env 配置到 overhead_analysis 跑测全流程【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant本文围绕 benchmarks/SETUP.md 展开完整讲解 Upsonic 仓库gpt-computer-assistant中基准测试Benchmarks子项目的标准环境搭建流程如何为benchmarks/目录创建独立的 uv 虚拟环境、安装四个关键依赖包、以可编辑模式安装upsonic框架本身、在仓库根目录配置.env密钥文件以及通过命令行参数与 Makefile 命令运行overhead_analysis基准测试并产出结果。读完后你可以独立搭建一套可复现的基准测试环境理解每个安装步骤在源码中的实际作用并按仓库约定的目录规范创建新的基准测试项目。基准测试目录结构与各文件职责在开始配置之前先明确benchmarks/目录的组成。SETUP.md 中给出的目录结构如下benchmarks/ ├── .venv/ # 虚拟环境在 gitignore 中 ├── .gitignore # Python、venv 等 ├── __init__.py ├── utils.py # 共享工具 ├── README.md # 主 README ├── SETUP.md # 本指南 ├── Makefile # 自动化命令 │ └── overhead_analysis/ # 第一个基准测试项目 ├── __init__.py ├── benchmark.py ├── test_cases.py ├── README.md └── results/各文件在基准测试体系中的角色可对照 benchmarks/README.md 核实utils.py所有基准测试项目共享的剖析工具包含MemoryProfiler对象大小、峰值内存跟踪、PerformanceProfiler计时与统计、BenchmarkReporter报告生成、JSON 导出。overhead_analysis/当前仓库内置的第一个基准测试项目做三方对比——Direct 直接 LLM 调用最小开销vs Agent无系统提示词vs Agent带系统提示词。其运行入口是 benchmarks/overhead_analysis/benchmark.py。Makefile封装了环境创建、依赖安装、跑测、清理等自动化命令详见后文。results/基准测试结果的输出目录JSON 文件保存原始数据Markdown 文件保存带对比表与样本输出的格式化报告。一个值得注意的实现细节基准测试代码通过把仓库根目录插入sys.path来定位框架代码。在 benchmarks/overhead_analysis/benchmark.py 中可以看到# Add parent directory to path sys.path.insert(0, str(Path(__file__).parent.parent.parent)) from upsonic import Agent, Direct, Task这就是为什么 SETUP.md 要求以uv pip install -e ..可编辑模式安装上层的upsonic包——基准测试直接from upsonic import ...必须保证当前虚拟环境内能解析到该包。方式一Makefile 快速搭建推荐benchmarks/QUICKSTART.md 与 SETUP.md 都指出 Makefile 是最省事的入口。核心三步cd benchmarks make setup # 创建虚拟环境 安装依赖 cd .. echo OPENAI_API_KEYsk-xxx .env cd benchmarks make run # 运行默认基准测试make setup在 benchmarks/Makefile 中实际做了三件事若.venv不存在执行uv venv创建虚拟环境已存在则跳过激活.venv后执行uv pip install pydantic python-dotenv pympler执行uv pip install -e ..以可编辑模式安装上层目录的upsonic框架。setup 完成后 Makefile 会提示接下来的步骤在父目录创建包含OPENAI_API_KEY的.env文件然后运行make run。此外 Makefile 提供了make test-env用于自检环境状态它会依次检查三件事并给出 ✓/✗ 反馈虚拟环境.venv是否存在父目录../.env文件是否存在在激活的 venv 中import upsonic是否成功。make test-env # 期望输出 # ✓ Virtual environment exists # ✓ .env file exists # ✓ Upsonic installed方式二手动分步搭建SETUP.md Quick Start 六步如果希望完全掌控每一步SETUP.md 给出的标准手动流程为# 1. 进入 benchmarks 目录 cd /path/to/Upsonic/benchmarks # 2. 创建虚拟环境仅首次 uv venv # 3. 激活虚拟环境 source .venv/bin/activate # Linux/Mac # 或 .venv\Scripts\activate # Windows # 4. 安装依赖仅首次 uv pip install pydantic python-dotenv pympler anthropic uv pip install -e .. # 5. 在仓库主目录创建环境文件 cd .. echo OPENAI_API_KEYyour-key-here .env echo ANTHROPIC_API_KEYyour-key-here .env # 可选 # 6. 运行基准测试 cd benchmarks python -m overhead_analysis.benchmark --list-tests为什么安装这四个包SETUP.md 把依赖分为「基准测试专用」与「框架自带」两组结合源码可以逐一验证其用途基准测试专用包包名用途源码证据pydantic结构化输出Structured Output基准测试中response_format使用 Pydantic 模型测试用例在 benchmarks/overhead_analysis/test_cases.py 中定义Task的response_format参数即依赖 Pydanticpython-dotenv加载.env环境变量benchmark.py 中from dotenv import load_dotenv并在 第 377 行 调用load_dotenv()pympler深度内存剖析可选benchmarks/utils.py 中measure_object_size会尝试from pympler import asizeof计算深拷贝大小导入失败时回退到sys.getsizeof的浅层大小——这正是文档标注其「optional」的原因anthropicAnthropic API 客户端仅在使用anthropic/...模型时需要框架自带依赖随uv pip install -e ..引入upsonic以可编辑模式安装后其 pyproject.toml 中声明的核心依赖自动进入环境包括openai2.2.0LLM provider、rich13.9.4终端 UI、pydantic2.10.5、python-dotenv1.0.1等。这也解释了 SETUP.md 中「Framework」一栏列出的upsonic、openai、rich的来源。需要注意版本差异手动流程显式安装了anthropic包而 Makefile 的setup目标只安装pydantic python-dotenv pympler见 Makefile 第 67-69 行——因为anthropic在 pyproject.toml 中属于可选的modelsextra。如果你要跑 Anthropic 模型对比如make run-compare按 SETUP.md 手动补装anthropic是正确做法。另外upsonic当前版本为0.77.3要求 Python3.10见 pyproject.toml。配置 .env位置与密钥要求SETUP.md 对.env的关键约定是文件放在仓库主目录benchmarks/的父目录而不是benchmarks/内部。cd .. echo OPENAI_API_KEYyour-key-here .env echo ANTHROPIC_API_KEYyour-key-here .env # Optional两个事实佐证了这一约定的必要性Makefile 会硬性检查../.envrun、run-all、run-compare等目标在执行前都会判断if [ ! -f ../.env ]不存在则直接报错退出并提示Create .env with: OPENAI_API_KEYyour-key见 benchmarks/Makefileload_dotenv()从当前工作目录向上查找基准测试从benchmarks/目录运行load_dotenv()默认会沿父目录向上搜索.env文件因此根目录的配置文件可以被找到。密钥配置要求OPENAI_API_KEY必需默认基准测试使用的模型为 OpenAI 模型ANTHROPIC_API_KEY可选仅在测试anthropic/...模型或运行make run-compare同时测 OpenAI 与 Anthropic时需要。另外benchmark.py 第 26 行 在模块加载阶段就设置了os.environ[UPSONIC_TELEMETRY] False即基准测试运行期间框架遥测是关闭的不会引入额外网络开销——这对测量基准的纯净性是有意为之的。运行基准测试命令行参数详解进入benchmarks/并激活虚拟环境后标准运行方式是模块方式调用cd benchmarks source .venv/bin/activate python -m overhead_analysis.benchmark # 运行默认测试用例 python -m overhead_analysis.benchmark --list-tests # 列出可用测试用例所有命令行参数由 benchmark.py 的main()中的argparse定义实际定义与默认值如下参数类型默认值说明--test-caseTEXTSimple Text Query运行指定测试用例如Math Problem--modelTEXTgpt-5-mini-2025-08-07模型标识支持逗号分隔的多个模型--iterationsINT5性能测量的迭代次数--all-testsflag关闭运行全部测试用例--list-testsflag关闭列出可用测试用例后退出典型用法组合来自 benchmarks/overhead_analysis/README.md# 指定单个测试用例 python -m overhead_analysis.benchmark --test-case Math Problem # 全部测试用例 python -m overhead_analysis.benchmark --all-tests # 指定不同模型 python -m overhead_analysis.benchmark --model openai/gpt-4o # 多模型对比逗号分隔 python -m overhead_analysis.benchmark --model openai/gpt-4o-mini,anthropic/claude-3-5-haiku-20241022 # 增加迭代次数文档建议至少 5 次以保证统计意义 python -m overhead_analysis.benchmark --iterations 10 --all-tests模型名称的自动校验--model传入的模型名会先经过 benchmark.py 中的validate_model()校验它会发起一次最小化的真实调用来确认模型可用并对常见错误做解析——404/not_found→ 报告Model not found401/authentication→ 报告Authentication failed. Check your API key.Unknown provider→ 报告Unknown provider: provider。校验失败时的输出形如❌ Invalid model invalid/model: Unknown provider: invalid Examples of valid model formats: openai/gpt-4o-mini anthropic/claude-3-5-haiku-20241022内置的五个测试用例覆盖从简单到复杂的不同场景Simple Text Query纯文本、Simple Structured OutputPydantic 结构化输出、Math Problem数学推理、Text Analysis复杂文本分析、Context-based Query带上下文的查询。要新增测试用例只需在 test_cases.py 中添加一个静态方法返回包含name、description、response_format、attachments、context键的字典。Makefile 命令全集SETUP.md 列出的 8 条常用命令加上 benchmarks/Makefile 中实际存在但文档未完全展开的命令整理如下make help可查看同一清单make setup # 创建 venv 并安装依赖 make install # 仅在已有 venv 中安装/升级依赖无 venv 时报错提示先跑 setup make run # 运行默认基准测试Simple Text Query make run-all # 运行全部测试用例Makefile 会提示“耗时数分钟且消耗 API 额度” make run-compare # 同时运行 openai/gpt-4o-mini 与 anthropic/claude-3-5-haiku-20241022 做跨供应商对比 make list # 列出可用测试用例 make results # 按修改时间列出 results/ 下最近的 JSON 结果 make clean # 清理 __pycache__、.pyc/.pyo、egg-info make clean-all # 在 clean 基础上删除 .venv 和 overhead_analysis/results 中的 JSON make help # 显示所有命令Makefile 中还提供了几条 SETUP.md 未提及的定制命令直接对应常用命令行参数make run-math # 等价于 --test-case Math Problem make run-structured # 等价于 --test-case Simple Structured Output make run-analysis # 等价于 --test-case Text Analysis make run-iterations N10 # 等价于 --iterations 10不传 N 会报错提示用法其中run-compare的依赖最严格它要求../.env中同时存在OPENAI_API_KEY和ANTHROPIC_API_KEY否则直接退出并提示补齐两个 key见 benchmarks/Makefile。结果输出JSON 原始数据与 Markdown 报告每次运行会在overhead_analysis/results/下生成成对的 JSON 与 Markdown 文件命名格式为测试用例_(模型)_时间戳.json/.mdresults/ ├── Simple_Text_Query_(gpt-4o-mini)_20260127_103045.json ├── Simple_Text_Query_(gpt-4o-mini)_20260127_103045.md ├── Math_Problem_(gpt-4o-mini)_20260127_103145.json └── ...JSON 文件原始指标数据可通过jq查看内容cat overhead_analysis/results/*.json | jq .Markdown 报告包含任务信息描述、响应格式、上下文、三方对比表Direct vs Agent 无提示词 vs Agent 带提示词涵盖速度、内存、成本、token 用量以及每种方式的样本输出。指标字段定义在 benchmarks/utils.py 的三个数据类中MemoryMetricsshallow_size_bytes对象自身大小、deep_size_bytes含全部引用、peak_memory_mb、current_memory_mbPerformanceMetricsinit_time_ms、execution_time_ms、total_time_ms、iterations以及多次运行后的mean/median/stdev/min/max_time_msCostMetricstotal_cost、input_tokens、output_tokens、total_tokens、cost_per_1k_tokens。多模型运行时终端还会额外打印一个「WINNERS」汇总块按mean_time_ms与total_cost/iterations分别选出最快的 Direct / Agent无提示词/ Agent带提示词以及最便宜的三者见 benchmark.py。故障排查SETUP.md 总结了四类典型问题这里结合 Makefile 与源码行为逐条说明1.ImportError: No module named X通常是虚拟环境未激活导致使用了系统 Pythonwhich python # 应显示 .venv/bin/python source .venv/bin/activate # 若不正确则重新激活 uv pip install package-name2.ModuleNotFoundError: No module named upsonic框架未以可编辑模式安装进当前 venvuv pip install -e ..或等价地执行make install前提是.venv已存在否则该目标会提示先运行make setup。3. API Key 报错确认.env位于仓库根目录且包含真实密钥cd /path/to/Upsonic echo OPENAI_API_KEYyour-actual-key .env注意区分「key 缺失」与「key 无效」前者表现为模型校验阶段的Authentication failed. Check your API key.后者可先用make test-env确认文件位置无误。4. Anthropic 账户余额不足若看到Your credit balance is too low to access the Anthropic API登录 Anthropic Console控制台网站在浏览器中访问console.anthropic.com进入 Billing 部分为账户充值重新运行基准测试。5. Makefile 层的环境报错QUICKSTART.md 补充了两个 Makefile 特有的报错场景及修复方式“Virtual environment not found”→ 运行make setup“.env file not found”→ 回到仓库根目录创建.env依赖损坏需要整体重建→make clean-all make setup完全重置。创建新的基准测试项目SETUP.md 约定新增基准测试项目复用现有虚拟环境只需建立新的子目录包# 虚拟环境已存在激活即可 source .venv/bin/activate # 创建新项目目录含 results 输出目录 mkdir -p your_benchmark/results # 编写代码后运行 python -m your_benchmark.benchmarkbenchmarks/README.md 进一步给出了推荐的项目骨架与模板benchmarks/ ├── your_benchmark_name/ │ ├── __init__.py │ ├── benchmark.py │ ├── test_cases.py (optional) │ ├── README.md │ └── results/ │ └── .gitkeep# your_benchmark_name/benchmark.py import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent.parent)) from benchmarks.utils import ( MemoryProfiler, PerformanceProfiler, BenchmarkReporter ) def run_benchmark(): # 你的基准测试逻辑 pass if __name__ __main__: run_benchmark()配套的最佳实践复用benchmarks.utils中的剖析工具结果以 JSON 存入各自的results/目录编写 README 说明运行方式与测量内容用多次迭代 均值/中位数/标准差做统计分析。实操 Tips 汇总每个终端会话都要激活虚拟环境source .venv/bin/activate否则命令会落到系统 Python 上升级某个包uv pip install --upgrade package-name查看当前 venv 内全部包uv pip list结果落盘位置固定为overhead_analysis/results/JSON 是原始数据Markdown 是带对比表和样本输出的报告make help随时查看全部 Makefile 命令make test-env是排查环境问题的第一步运行前提首次运行因模型加载可能较慢LLM 调用需要网络每次运行都会产生真实 API 费用--iterations越大越可靠但也越贵README 建议迭代次数不低于 5 次以获得统计意义。小结Upsonic 的基准测试环境设计遵循「独立 venv 可编辑安装框架 根目录.env」三要素uv venv保证依赖隔离uv pip install -e ..让benchmarks/内的代码直接引用仓库中的upsonic源码根目录.env统一承载各家 LLM 的 API 密钥。手动六步流程与make setup等价但后者更不容易出错跑测环节通过python -m overhead_analysis.benchmark的五个参数--test-case、--model、--iterations、--all-tests、--list-tests或 Makefile 封装命令控制模型名在运行前会被真实调用的方式自动校验。按本文流程操作后results/目录下的 JSON/Markdown 成对文件即可作为 Direct 与 Agent 两种调用方式在内存、耗时、成本三维度的可复现对比依据。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Upsonic 基准测试环境搭建与运行指南：虚拟环境、依赖安装、.env 配置到 overhead_analysis 跑测全流程
Upsonic 基准测试环境搭建与运行指南虚拟环境、依赖安装、.env 配置到 overhead_analysis 跑测全流程【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant本文围绕 benchmarks/SETUP.md 展开完整讲解 Upsonic 仓库gpt-computer-assistant中基准测试Benchmarks子项目的标准环境搭建流程如何为benchmarks/目录创建独立的 uv 虚拟环境、安装四个关键依赖包、以可编辑模式安装upsonic框架本身、在仓库根目录配置.env密钥文件以及通过命令行参数与 Makefile 命令运行overhead_analysis基准测试并产出结果。读完后你可以独立搭建一套可复现的基准测试环境理解每个安装步骤在源码中的实际作用并按仓库约定的目录规范创建新的基准测试项目。基准测试目录结构与各文件职责在开始配置之前先明确benchmarks/目录的组成。SETUP.md 中给出的目录结构如下benchmarks/ ├── .venv/ # 虚拟环境在 gitignore 中 ├── .gitignore # Python、venv 等 ├── __init__.py ├── utils.py # 共享工具 ├── README.md # 主 README ├── SETUP.md # 本指南 ├── Makefile # 自动化命令 │ └── overhead_analysis/ # 第一个基准测试项目 ├── __init__.py ├── benchmark.py ├── test_cases.py ├── README.md └── results/各文件在基准测试体系中的角色可对照 benchmarks/README.md 核实utils.py所有基准测试项目共享的剖析工具包含MemoryProfiler对象大小、峰值内存跟踪、PerformanceProfiler计时与统计、BenchmarkReporter报告生成、JSON 导出。overhead_analysis/当前仓库内置的第一个基准测试项目做三方对比——Direct 直接 LLM 调用最小开销vs Agent无系统提示词vs Agent带系统提示词。其运行入口是 benchmarks/overhead_analysis/benchmark.py。Makefile封装了环境创建、依赖安装、跑测、清理等自动化命令详见后文。results/基准测试结果的输出目录JSON 文件保存原始数据Markdown 文件保存带对比表与样本输出的格式化报告。一个值得注意的实现细节基准测试代码通过把仓库根目录插入sys.path来定位框架代码。在 benchmarks/overhead_analysis/benchmark.py 中可以看到# Add parent directory to path sys.path.insert(0, str(Path(__file__).parent.parent.parent)) from upsonic import Agent, Direct, Task这就是为什么 SETUP.md 要求以uv pip install -e ..可编辑模式安装上层的upsonic包——基准测试直接from upsonic import ...必须保证当前虚拟环境内能解析到该包。方式一Makefile 快速搭建推荐benchmarks/QUICKSTART.md 与 SETUP.md 都指出 Makefile 是最省事的入口。核心三步cd benchmarks make setup # 创建虚拟环境 安装依赖 cd .. echo OPENAI_API_KEYsk-xxx .env cd benchmarks make run # 运行默认基准测试make setup在 benchmarks/Makefile 中实际做了三件事若.venv不存在执行uv venv创建虚拟环境已存在则跳过激活.venv后执行uv pip install pydantic python-dotenv pympler执行uv pip install -e ..以可编辑模式安装上层目录的upsonic框架。setup 完成后 Makefile 会提示接下来的步骤在父目录创建包含OPENAI_API_KEY的.env文件然后运行make run。此外 Makefile 提供了make test-env用于自检环境状态它会依次检查三件事并给出 ✓/✗ 反馈虚拟环境.venv是否存在父目录../.env文件是否存在在激活的 venv 中import upsonic是否成功。make test-env # 期望输出 # ✓ Virtual environment exists # ✓ .env file exists # ✓ Upsonic installed方式二手动分步搭建SETUP.md Quick Start 六步如果希望完全掌控每一步SETUP.md 给出的标准手动流程为# 1. 进入 benchmarks 目录 cd /path/to/Upsonic/benchmarks # 2. 创建虚拟环境仅首次 uv venv # 3. 激活虚拟环境 source .venv/bin/activate # Linux/Mac # 或 .venv\Scripts\activate # Windows # 4. 安装依赖仅首次 uv pip install pydantic python-dotenv pympler anthropic uv pip install -e .. # 5. 在仓库主目录创建环境文件 cd .. echo OPENAI_API_KEYyour-key-here .env echo ANTHROPIC_API_KEYyour-key-here .env # 可选 # 6. 运行基准测试 cd benchmarks python -m overhead_analysis.benchmark --list-tests为什么安装这四个包SETUP.md 把依赖分为「基准测试专用」与「框架自带」两组结合源码可以逐一验证其用途基准测试专用包包名用途源码证据pydantic结构化输出Structured Output基准测试中response_format使用 Pydantic 模型测试用例在 benchmarks/overhead_analysis/test_cases.py 中定义Task的response_format参数即依赖 Pydanticpython-dotenv加载.env环境变量benchmark.py 中from dotenv import load_dotenv并在 第 377 行 调用load_dotenv()pympler深度内存剖析可选benchmarks/utils.py 中measure_object_size会尝试from pympler import asizeof计算深拷贝大小导入失败时回退到sys.getsizeof的浅层大小——这正是文档标注其「optional」的原因anthropicAnthropic API 客户端仅在使用anthropic/...模型时需要框架自带依赖随uv pip install -e ..引入upsonic以可编辑模式安装后其 pyproject.toml 中声明的核心依赖自动进入环境包括openai2.2.0LLM provider、rich13.9.4终端 UI、pydantic2.10.5、python-dotenv1.0.1等。这也解释了 SETUP.md 中「Framework」一栏列出的upsonic、openai、rich的来源。需要注意版本差异手动流程显式安装了anthropic包而 Makefile 的setup目标只安装pydantic python-dotenv pympler见 Makefile 第 67-69 行——因为anthropic在 pyproject.toml 中属于可选的modelsextra。如果你要跑 Anthropic 模型对比如make run-compare按 SETUP.md 手动补装anthropic是正确做法。另外upsonic当前版本为0.77.3要求 Python3.10见 pyproject.toml。配置 .env位置与密钥要求SETUP.md 对.env的关键约定是文件放在仓库主目录benchmarks/的父目录而不是benchmarks/内部。cd .. echo OPENAI_API_KEYyour-key-here .env echo ANTHROPIC_API_KEYyour-key-here .env # Optional两个事实佐证了这一约定的必要性Makefile 会硬性检查../.envrun、run-all、run-compare等目标在执行前都会判断if [ ! -f ../.env ]不存在则直接报错退出并提示Create .env with: OPENAI_API_KEYyour-key见 benchmarks/Makefileload_dotenv()从当前工作目录向上查找基准测试从benchmarks/目录运行load_dotenv()默认会沿父目录向上搜索.env文件因此根目录的配置文件可以被找到。密钥配置要求OPENAI_API_KEY必需默认基准测试使用的模型为 OpenAI 模型ANTHROPIC_API_KEY可选仅在测试anthropic/...模型或运行make run-compare同时测 OpenAI 与 Anthropic时需要。另外benchmark.py 第 26 行 在模块加载阶段就设置了os.environ[UPSONIC_TELEMETRY] False即基准测试运行期间框架遥测是关闭的不会引入额外网络开销——这对测量基准的纯净性是有意为之的。运行基准测试命令行参数详解进入benchmarks/并激活虚拟环境后标准运行方式是模块方式调用cd benchmarks source .venv/bin/activate python -m overhead_analysis.benchmark # 运行默认测试用例 python -m overhead_analysis.benchmark --list-tests # 列出可用测试用例所有命令行参数由 benchmark.py 的main()中的argparse定义实际定义与默认值如下参数类型默认值说明--test-caseTEXTSimple Text Query运行指定测试用例如Math Problem--modelTEXTgpt-5-mini-2025-08-07模型标识支持逗号分隔的多个模型--iterationsINT5性能测量的迭代次数--all-testsflag关闭运行全部测试用例--list-testsflag关闭列出可用测试用例后退出典型用法组合来自 benchmarks/overhead_analysis/README.md# 指定单个测试用例 python -m overhead_analysis.benchmark --test-case Math Problem # 全部测试用例 python -m overhead_analysis.benchmark --all-tests # 指定不同模型 python -m overhead_analysis.benchmark --model openai/gpt-4o # 多模型对比逗号分隔 python -m overhead_analysis.benchmark --model openai/gpt-4o-mini,anthropic/claude-3-5-haiku-20241022 # 增加迭代次数文档建议至少 5 次以保证统计意义 python -m overhead_analysis.benchmark --iterations 10 --all-tests模型名称的自动校验--model传入的模型名会先经过 benchmark.py 中的validate_model()校验它会发起一次最小化的真实调用来确认模型可用并对常见错误做解析——404/not_found→ 报告Model not found401/authentication→ 报告Authentication failed. Check your API key.Unknown provider→ 报告Unknown provider: provider。校验失败时的输出形如❌ Invalid model invalid/model: Unknown provider: invalid Examples of valid model formats: openai/gpt-4o-mini anthropic/claude-3-5-haiku-20241022内置的五个测试用例覆盖从简单到复杂的不同场景Simple Text Query纯文本、Simple Structured OutputPydantic 结构化输出、Math Problem数学推理、Text Analysis复杂文本分析、Context-based Query带上下文的查询。要新增测试用例只需在 test_cases.py 中添加一个静态方法返回包含name、description、response_format、attachments、context键的字典。Makefile 命令全集SETUP.md 列出的 8 条常用命令加上 benchmarks/Makefile 中实际存在但文档未完全展开的命令整理如下make help可查看同一清单make setup # 创建 venv 并安装依赖 make install # 仅在已有 venv 中安装/升级依赖无 venv 时报错提示先跑 setup make run # 运行默认基准测试Simple Text Query make run-all # 运行全部测试用例Makefile 会提示“耗时数分钟且消耗 API 额度” make run-compare # 同时运行 openai/gpt-4o-mini 与 anthropic/claude-3-5-haiku-20241022 做跨供应商对比 make list # 列出可用测试用例 make results # 按修改时间列出 results/ 下最近的 JSON 结果 make clean # 清理 __pycache__、.pyc/.pyo、egg-info make clean-all # 在 clean 基础上删除 .venv 和 overhead_analysis/results 中的 JSON make help # 显示所有命令Makefile 中还提供了几条 SETUP.md 未提及的定制命令直接对应常用命令行参数make run-math # 等价于 --test-case Math Problem make run-structured # 等价于 --test-case Simple Structured Output make run-analysis # 等价于 --test-case Text Analysis make run-iterations N10 # 等价于 --iterations 10不传 N 会报错提示用法其中run-compare的依赖最严格它要求../.env中同时存在OPENAI_API_KEY和ANTHROPIC_API_KEY否则直接退出并提示补齐两个 key见 benchmarks/Makefile。结果输出JSON 原始数据与 Markdown 报告每次运行会在overhead_analysis/results/下生成成对的 JSON 与 Markdown 文件命名格式为测试用例_(模型)_时间戳.json/.mdresults/ ├── Simple_Text_Query_(gpt-4o-mini)_20260127_103045.json ├── Simple_Text_Query_(gpt-4o-mini)_20260127_103045.md ├── Math_Problem_(gpt-4o-mini)_20260127_103145.json └── ...JSON 文件原始指标数据可通过jq查看内容cat overhead_analysis/results/*.json | jq .Markdown 报告包含任务信息描述、响应格式、上下文、三方对比表Direct vs Agent 无提示词 vs Agent 带提示词涵盖速度、内存、成本、token 用量以及每种方式的样本输出。指标字段定义在 benchmarks/utils.py 的三个数据类中MemoryMetricsshallow_size_bytes对象自身大小、deep_size_bytes含全部引用、peak_memory_mb、current_memory_mbPerformanceMetricsinit_time_ms、execution_time_ms、total_time_ms、iterations以及多次运行后的mean/median/stdev/min/max_time_msCostMetricstotal_cost、input_tokens、output_tokens、total_tokens、cost_per_1k_tokens。多模型运行时终端还会额外打印一个「WINNERS」汇总块按mean_time_ms与total_cost/iterations分别选出最快的 Direct / Agent无提示词/ Agent带提示词以及最便宜的三者见 benchmark.py。故障排查SETUP.md 总结了四类典型问题这里结合 Makefile 与源码行为逐条说明1.ImportError: No module named X通常是虚拟环境未激活导致使用了系统 Pythonwhich python # 应显示 .venv/bin/python source .venv/bin/activate # 若不正确则重新激活 uv pip install package-name2.ModuleNotFoundError: No module named upsonic框架未以可编辑模式安装进当前 venvuv pip install -e ..或等价地执行make install前提是.venv已存在否则该目标会提示先运行make setup。3. API Key 报错确认.env位于仓库根目录且包含真实密钥cd /path/to/Upsonic echo OPENAI_API_KEYyour-actual-key .env注意区分「key 缺失」与「key 无效」前者表现为模型校验阶段的Authentication failed. Check your API key.后者可先用make test-env确认文件位置无误。4. Anthropic 账户余额不足若看到Your credit balance is too low to access the Anthropic API登录 Anthropic Console控制台网站在浏览器中访问console.anthropic.com进入 Billing 部分为账户充值重新运行基准测试。5. Makefile 层的环境报错QUICKSTART.md 补充了两个 Makefile 特有的报错场景及修复方式“Virtual environment not found”→ 运行make setup“.env file not found”→ 回到仓库根目录创建.env依赖损坏需要整体重建→make clean-all make setup完全重置。创建新的基准测试项目SETUP.md 约定新增基准测试项目复用现有虚拟环境只需建立新的子目录包# 虚拟环境已存在激活即可 source .venv/bin/activate # 创建新项目目录含 results 输出目录 mkdir -p your_benchmark/results # 编写代码后运行 python -m your_benchmark.benchmarkbenchmarks/README.md 进一步给出了推荐的项目骨架与模板benchmarks/ ├── your_benchmark_name/ │ ├── __init__.py │ ├── benchmark.py │ ├── test_cases.py (optional) │ ├── README.md │ └── results/ │ └── .gitkeep# your_benchmark_name/benchmark.py import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent.parent)) from benchmarks.utils import ( MemoryProfiler, PerformanceProfiler, BenchmarkReporter ) def run_benchmark(): # 你的基准测试逻辑 pass if __name__ __main__: run_benchmark()配套的最佳实践复用benchmarks.utils中的剖析工具结果以 JSON 存入各自的results/目录编写 README 说明运行方式与测量内容用多次迭代 均值/中位数/标准差做统计分析。实操 Tips 汇总每个终端会话都要激活虚拟环境source .venv/bin/activate否则命令会落到系统 Python 上升级某个包uv pip install --upgrade package-name查看当前 venv 内全部包uv pip list结果落盘位置固定为overhead_analysis/results/JSON 是原始数据Markdown 是带对比表和样本输出的报告make help随时查看全部 Makefile 命令make test-env是排查环境问题的第一步运行前提首次运行因模型加载可能较慢LLM 调用需要网络每次运行都会产生真实 API 费用--iterations越大越可靠但也越贵README 建议迭代次数不低于 5 次以获得统计意义。小结Upsonic 的基准测试环境设计遵循「独立 venv 可编辑安装框架 根目录.env」三要素uv venv保证依赖隔离uv pip install -e ..让benchmarks/内的代码直接引用仓库中的upsonic源码根目录.env统一承载各家 LLM 的 API 密钥。手动六步流程与make setup等价但后者更不容易出错跑测环节通过python -m overhead_analysis.benchmark的五个参数--test-case、--model、--iterations、--all-tests、--list-tests或 Makefile 封装命令控制模型名在运行前会被真实调用的方式自动校验。按本文流程操作后results/目录下的 JSON/Markdown 成对文件即可作为 Direct 与 Agent 两种调用方式在内存、耗时、成本三维度的可复现对比依据。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
