AI 应用LLMOps模型评测AI AgentAI 安全治理【免费下载链接】RagaAI-CatalystPython SDK for Agent AI Observability, Monitoring and Evaluation Framework. Includes features like agent, llm and tools tracing, debugging multi-agentic system, self-hosted dashboard and advanced analytics with timeline and execution graph view项目地址https://gitcode.com/gh_mirrors/ra/RagaAI-Catalyst点击查看免费下载RagaAI Catalyst 是一个面向 Agent AI 的可观测性、监控与评估框架Python SDK而tests/测试套件是验证其核心组件、关键工作流与多 LLM Provider 兼容性的官方质量保障体系。本文将以 tests/README.md 为骨架完整讲解从 Conda 环境搭建、.env密钥配置到 pytest 运行与自动化报告生成的端到端流程并结合仓库源码剖析报告脚本的解析逻辑与测试用例的设计思路帮助你快速上手并二次复用这套测试体系。测试套件概览它在验证什么根据 tests/README.md 的说明该测试套件基于 pytest 构建验证 RagaAI Catalyst 的如下能力核心组件单元测试针对配置初始化、数据集管理、评估、提示词管理等核心模块的独立验证关键工作流集成测试覆盖从 LLM 调用产生 Trace、落盘到上传的完整链路多 LLM Provider 测试同一套用例参数化跑通 OpenAI、Groq、Azure、GoogleGemini、LiteLLM 等多个模型供应商自动化测试报告能力一键运行全部测试并输出带通过/失败/错误统计的结构化报告。这一设计原则在 pyproject.toml 的 pytest 配置中也有印证testpaths [tests]将tests/目录指定为默认的测试发现路径因此直接执行pytest或python -m pytest即可自动收集该目录下的全部用例。测试目录结构解析tests/ ├── README.md # 测试套件使用说明本文档 ├── environment.yml # Conda 环境定义Python 3.12 全部测试依赖 ├── run_pytest_and_print_and_save_results.py # 一键运行并生成报告的脚本 ├── table_result.png # 报告输出的示例截图 ├── examples/ # 基于官方示例的集成测试多框架 多 Provider │ ├── all_llm_provider/ # 多 LLM Provider 参数化测试 │ ├── crewai/scifi_writer/ # CrewAI 示例测试 │ ├── custom_agents/travel_agent/ # 自定义 Agent 示例测试 │ ├── haystack/news_fetching/ # Haystack 示例测试 │ ├── langchain/medical_rag/ # LangChain RAG 示例测试 │ ├── langgraph/personal_research_assistant/ # LangGraph 示例测试 │ ├── llamaindex_examples/legal_research_rag/# LlamaIndex 示例测试 │ ├── smolagents/most_upvoted_paper/ # SmolAgents 示例测试 │ └── test_utils/ # 测试辅助工具命令执行、Trace 解析 └── test_catalyst/ # Catalyst 核心组件测试 ├── test_data/ # 测试数据PDF/CSV 等 ├── test_dataset.py ├── test_evaluation.py ├── test_evaluation_metrics.py ├── test_prompt_manager.py ├── test_synthetic_data_generation.py ├── test_base_tracer_metrics.py ├── test_base_tracer_add_metrics.py └── test_the_configuration.py可以看到测试被划分为两大块examples/下是针对官方示例应用CrewAI、Haystack、LangChain、LangGraph、LlamaIndex、SmolAgents 等框架的端到端集成测试test_catalyst/下则是直接针对 SDK 核心 API数据集、评估、Prompt 管理、Tracer、合成数据生成、配置的单元测试。examples/test_utils/中的 get_trace_data.py 与 get_components.py 负责在集成测试中运行示例脚本、从日志中提取 Trace 落盘路径并解析 JSON从而验证 Trace 数据的完整性与组件调用顺序。搭建 Conda 测试环境测试套件使用 Conda 管理环境环境定义文件位于 tests/environment.yml。第一步创建环境conda env create -f tests/environment.yml第二步激活环境conda activate ragaai_pytest_env环境名称来自environment.yml首行的name: ragaai_pytest_env字段可自行确认无需手工猜测。环境文件关键内容解读从 tests/environment.yml 的依赖清单可以确认该测试环境的几个关键特征Python 版本python3.12.2python_abi3.12与项目主 SDK 声明的3.10,3.13.2见 pyproject.toml兼容测试框架pytest8.3.5另含pytest生态的pluggy、iniconfig、tomli等依赖SDK 本体ragaai-catalyst2.1.6.4即被测对象以已安装包形式存在多 LLM Provider SDKopenai1.70.0、anthropic0.49.0、groq0.13.1、google-generativeai0.8.3、vertexai1.71.1、litellm1.60.2等覆盖 README 中列出的所有 ProviderAgent 框架langchain0.3.23、langgraph0.3.25、llama-index0.12.28、crewai0.108.0、haystack-ai2.12.0、smolagents1.13.0可观测性基础设施opentelemetry-sdk1.31.1、opentelemetry-exporter-otlp1.31.1以及全套openinference-instrumentation-*仪器化库openai、anthropic、groq、langchain、llama-index、vertexai、crewai、haystack、smolagents、litellm、bedrock、mistralai 等与 SDK 的 Trace 采集机制一一对应辅助依赖python-dotenv1.0.1加载.env、requests2.32.3、tabulate报告表格渲染、rich、pandas、numpy、torch2.6.0、sentence-transformers4.0.2评估/嵌入场景。如果你不想使用 Conda仓库根目录还提供了 tests_requirements.txt其中声明了集成测试所需的框架级依赖vertexai、crewai、haystack-ai、langgraph、smolagents、sentence-transformers 等可用于pip install -r tests_requirements.txt的等价安装路径。配置.env环境变量测试需要访问多个 LLM Provider 与 RagaAI Catalyst 云端服务因此在项目根目录创建.env文件并按需填入密钥。完整模板如下来自 tests/README.md#OpenAI OPENAI_API_KEY #Anthropic ANTHROPIC_API_KEY #Groq GROQ_API_KEY #Azure AZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY AZURE_OPENAI_API_VERSION #Google GOOGLE_API_KEY #Gemini GEMINI_API_KEY #Vertex AI Setup PROJECT_NAME LOCATION # RagaAI RAGAAI_CATALYST_BASE_URLhttps://catalyst.raga.ai/api # use this url only RAGAAI_CATALYST_ACCESS_KEY RAGAAI_CATALYST_SECRET_KEY RAGAAI_PROJECT_NAMEprompt_metric_dataset # use this dataset only RAGAAI_DATASET_NAMEpytest_dataset # Other APIs TAVILY_API_KEY SERPERDEV_API_KEY各变量的作用域说明如下变量用途OPENAI_API_KEYOpenAI / GPT 系列模型调用如gpt-4o-miniANTHROPIC_API_KEYAnthropic Claude 系列模型调用GROQ_API_KEYGroq 加速推理服务如llama3-8b-8192AZURE_OPENAI_*Azure OpenAI 的 Endpoint、密钥与 API 版本GOOGLE_API_KEY/GEMINI_API_KEYGoogle Gemini 模型如gemini-1.5-flashPROJECT_NAME/LOCATIONGoogle Vertex AI 的项目名与区域RAGAAI_CATALYST_BASE_URLCatalyst 服务地址README 明确要求仅使用https://catalyst.raga.ai/apiRAGAAI_CATALYST_ACCESS_KEY/RAGAAI_CATALYST_SECRET_KEYCatalyst 鉴权凭证Access Key 与 Secret KeyRAGAAI_PROJECT_NAME/RAGAAI_DATASET_NAME测试使用的项目与数据集README 要求项目固定为prompt_metric_dataset、数据集固定为pytest_datasetTAVILY_API_KEY/SERPERDEV_API_KEY搜索类工具用于带联网检索能力的 Agent 示例从源码看RAGAAI_PROJECT_NAME与RAGAAI_DATASET_NAME的取值并非可随意更换在 tests/examples/all_llm_provider/config.py 中Tracer 初始化时即硬编码了project_nameprompt_metric_dataset、dataset_namepytest_dataset与 README 中的注释约束完全一致。同时 test_the_configuration.py 也验证了缺少 Access Key/Secret Key 时初始化会抛出ValueError提示必须先设置环境变量无效密钥会抛认证失败异常无效 base_url 会抛ConnectionError这解释了.env中 RagaAI 三项配置为何是测试能否运行的前提。密钥加载由python-dotenv完成示例与测试代码中普遍使用load_dotenv()后通过os.getenv(...)读取。运行测试方式一直接用 pytest 运行全部测试python -m pytest testspytest 会按模块逐个执行用例并以.通过、F失败、E错误实时输出每个用例的状态同时附带进度百分比。方式二按需筛选测试借助 pytest 的-k表达式可以只跑某一类用例例如仅运行配置相关测试python -m pytest tests -k configuration对于集成测试还可进一步限定到具体文件例如仅验证多 LLM Provider 场景python -m pytest tests/examples/all_llm_provider/test_all_llm_provider.py方式三一键运行并生成完整报告python tests/run_pytest_and_print_and_save_results.py该脚本在控制台打印结构化报告并自动将报告保存为时间戳命名的test_report_YYYYMMDD_HHMMSS.txt文件仓库根目录下已有一份历史产物 test_report_20250407_183101.txt 可供参考。自动化报告脚本的源码级解析run_pytest_and_print_and_save_results.py 是测试套件自动化能力的核心整个流程由四个函数串联逻辑清晰、可独立复用1.run_pytest_and_generate_report()编排入口脚本先记录start_time通过subprocess.run(python -m pytest, ...)捕获 pytest 的 stdout 作为原始输出注意它运行的是全量测试收集范围仍受 pyproject.toml 的testpaths [tests]约束随后计算耗时精确到分钟再依次调用解析、生成、打印与保存。2.parse_pytest_output(output)正则解析测试结果该函数用正则^(.*\.py)\s([.EF])逐行匹配 pytest 的进度行形如test_dataset.py ....F [55%]并按字符计数区分状态passed result_str.count(.)failed result_str.count(F)errors result_str.count(E)最终为每个测试模块产出{module, count, passed, failed, errors}的结构化字典列表这是整份报告的数据基础。3.generate_test_report(test_results, duration)生成报告文本函数先汇总全局统计总用例数、通过/失败/错误数及百分比再为每个模块判定状态符号——有错误标记为有失败标记为❌全部通过标记为✅——并使用tabulate以fancy_grid样式渲染出六列表格Test Module | Tests | Passed | Failed | Errors | Status。若存在失败或错误还会追加 Problematic Tests 区块逐条列出问题模块及其失败/错误数量并提示需要查看测试日志定位具体问题方便后续排查。4.save_report(report)落盘保存默认以test_report_{datetime.now().strftime(%Y%m%d_%H%M%S)}.txt命名保存报告文件并打印绝对路径。这解释了仓库根目录下test_report_20250407_183101.txt这类文件名20250407_183101即 2025-04-07 18:31:01的来源。报告输出示例以仓库中的历史报告 test_report_20250407_183101.txt 为例真实报告结构如下TEST EXECUTION REPORT Date: 2025-04-07 18:31:01 Summary: - Total Tests: 104 - Passed: 50 (48.1%) - Failed: 5 (4.8%) - Errors: 49 (47.1%)其 Detailed Test Results 部分展示了 17 个测试模块各自的通过/失败/错误计数与状态符号其中examples/all_llm_provider/test_all_llm_provider.py10 个用例全部通过 ✅、各框架示例测试CrewAI、Haystack、LangChain、LangGraph、LlamaIndex、SmolAgents均为 1 个用例通过而test_dataset.py、test_evaluation.py、test_prompt_manager.py等模块因缺少云端环境而出现批量错误。报告末尾的 Problematic Tests 区块会将这些模块与数量汇总提示需要检查测试日志。报告中模块级的状态速览如下图所示历史报告截图绿色 ✅ 表示模块全通过、红色 ❌ 表示存在失败从源码看测试设计多 LLM Provider 参数化测试tests/examples/all_llm_provider/是测试不同 LLM Provider这一目标的直接体现其测试用例 test_all_llm_provider.py 采用 pytest 参数化设计pytest.mark.parametrize(provider, model, async_mode, [ # OpenAI (openai, gpt-4o-mini, True), (openai, gpt-4o-mini, False), # LiteLLM (litellm, gpt-4o-mini, True), (litellm, gpt-4o-mini, False), # Azure (azure, azure-gpt-4o-mini, True), (azure, azure-gpt-4o-mini, False), # Google (google, gemini-1.5-flash, True), (google, gemini-1.5-flash, False), # Chat Google (chat_google, gemini-1.5-flash, True), (chat_google, gemini-1.5-flash, False), ]) def test_all_llm_provider(provider: str, model: str, async_mode: bool): command fpython all_llm_provider.py --model {model} --provider {provider} --async_llm {async_mode} output run_command(command, cwdcwd) locations extract_information(output) data load_trace_data(locations) component_sequence get_component_structure_and_sequence(data) assert len(component_sequence) 1, fExpected 1 component, got {len(component_sequence)}该用例的核心验证逻辑是为每个(provider, model, async_mode)组合运行 all_llm_provider.py 示例 → 从运行日志中提取 Trace 落盘路径 → 加载 Trace JSON → 校验组件结构序列恰好为 1 个组件。其中 Trace 路径的提取与 JSON 加载由 get_trace_data.py 完成它通过正则Trace saved to (.*)与Submitting new upload task for file: (.*)从日志中捕获文件位置再挑选内容量最大的 JSON 作为有效 Trace。同参数下同步async_modeFalse与异步async_modeTrue两种模式都会被覆盖从而验证 SDK 在同步/异步两条调用路径上的 Trace 采集一致性。文件中 Anthropic 与 Groq 的参数组被注释保留说明该用例支持按需启用更多 Provider 组合。测试套件与 SDK 核心的联动tests/test_catalyst/下的用例直接面向 SDK 公开 API。以 test_the_configuration.py 为例它使用unittest.mock.patch模拟网络请求覆盖了如下行为RagaAICatalyst.get_token()的成功与失败路径失败时抛 Authentication failedproject_use_cases()、list_projects()的成功返回与网络异常兜底网络异常返回空列表create_project()的成功创建与重名冲突抛 already exists 错误list_metrics()的指标列表获取缺失凭证、无效凭证、无效 base_url 三种初始化异常场景。这些测试既验证了 SDK 与 Catalyst 云端 API 的契约也验证了错误处理分支与.env配置一节中必须正确填写 RagaAI 三项配置的要求互为印证。运行完整套件前建议先执行python -m pytest tests/test_catalyst/test_the_configuration.py确认本地配置与网络连通性正常再运行全量集成测试可有效缩短问题定位范围。小结RagaAI Catalyst 的测试套件提供了一条清晰的工程质量保障路径用conda env create -f tests/environment.yml一键复现环境用.env集中管理多 Provider 密钥用python -m pytest tests完成全量验证用 run_pytest_and_print_and_save_results.py 自动生成带统计与问题定位的结构化报告。无论是验证 SDK 新版本兼容性、排查多 LLM Provider 调用差异还是为 Catalyst 集成测试建立 CI 基线本文介绍的流程与脚本都可以直接复用。赞分享AI 应用LLMOps模型评测AI AgentAI 安全治理【免费下载链接】RagaAI-CatalystPython SDK for Agent AI Observability, Monitoring and Evaluation Framework. Includes features like agent, llm and tools tracing, debugging multi-agentic system, self-hosted dashboard and advanced analytics with timeline and execution graph view项目地址https://gitcode.com/gh_mirrors/ra/RagaAI-Catalyst点击查看免费下载相关推荐Telepathy-Community架构解析核心Python模块与Telethon API交互原理Telepathy Community架构解析核心Python模块与Telethon API交互原理 Telepathy Community是一款强大的开源OESP-TEE 测试套件实战指南基于 ESP-IDF pytest 框架的 TEE 单元测试与 CI 集成ESP TEE 测试套件实战指南基于 ESP IDF pytest 框架的 TEE 单元测试与 CI 集成 导读 本指南以 ESP IDF 仓库中 compo物联网嵌入式OpenMed 测试套件深度指南基于 pytest 的离线优先单元测试与集成测试实践OpenMed 测试套件深度指南基于 pytest 的离线优先单元测试与集成测试实践 本指南以 OpenMed 仓库的 tests/README.md htt人工智能NLP医疗健康数据脱敏本地部署大模型AI 应用MCP 服务联邦学习上一篇OpenUSD移动端终极指南iOS/visionOS编译优化与性能调优下一篇QuickRecorder 5 分钟上手Mac 免驱动录屏的 6 个实用场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考