{
"canonical_name": "raga-ai-hub/RagaAI-Catalyst",
"compilation_id": "pack_65628f36d45649be88753c157a3f596d",
"created_at": "2026-05-21T05:25:42.380870+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install ragaai-catalyst` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install ragaai-catalyst",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_eda39057ab244351a442c25aab6eb404"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_e9f46a95a2bd64780301a44911bd96c2",
"canonical_name": "raga-ai-hub/RagaAI-Catalyst",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/raga-ai-hub/RagaAI-Catalyst",
"slug": "ragaai-catalyst",
"source_packet_id": "phit_92f4f8734e654217b238e9d9cfa14eee",
"source_validation_id": "dval_25e4e7e68e0a4bbf81b3b4fcc045b8ff"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 local_cli的用户",
"github_forks": 3607,
"github_stars": 16156,
"one_liner_en": "Python 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",
"one_liner_zh": "Python 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",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "RagaAI-Catalyst",
"title_zh": "RagaAI-Catalyst 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_92f4f8734e654217b238e9d9cfa14eee",
"page_model": {
"artifacts": {
"artifact_slug": "ragaai-catalyst",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install ragaai-catalyst",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/raga-ai-hub/RagaAI-Catalyst#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Python 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"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.1.7.1",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Standardizing Agent Commerce: Merxex Integration Proposal",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.1.6",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.2.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.2.4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v2.1.5",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_daf5807f609141008dc6aaadbc15d774 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.1.6.2",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.4",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0790ea07d026457a8eb6bf9e454fdcfa | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.1.6.4",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.2.1",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_f1b8373166c14c4dba527f91193c93f1 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：2.2.1",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：2.1.7.1。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 28,
"forks": 3607,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 16156
},
"source_url": "https://github.com/raga-ai-hub/RagaAI-Catalyst",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Python 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",
"title": "RagaAI-Catalyst 能力包",
"trial_prompt": "# RagaAI-Catalyst - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 RagaAI-Catalyst 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Python 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 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. configuration：配置与认证。围绕“配置与认证”模拟一次用户任务，不展示安装或运行结果。\n2. project-management：项目管理。围绕“项目管理”模拟一次用户任务，不展示安装或运行结果。\n3. dataset-management：数据集管理。围绕“数据集管理”模拟一次用户任务，不展示安装或运行结果。\n4. evaluation：评估管理。围绕“评估管理”模拟一次用户任务，不展示安装或运行结果。\n5. agentic-tracing：智能体追踪系统。围绕“智能体追踪系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. configuration\n输入：用户提供的“配置与认证”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. project-management\n输入：用户提供的“项目管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. dataset-management\n输入：用户提供的“数据集管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. evaluation\n输入：用户提供的“评估管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. agentic-tracing\n输入：用户提供的“智能体追踪系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / configuration：Step 1 必须围绕“配置与认证”形成一个小中间产物，并等待用户确认。\n- Step 2 / project-management：Step 2 必须围绕“项目管理”形成一个小中间产物，并等待用户确认。\n- Step 3 / dataset-management：Step 3 必须围绕“数据集管理”形成一个小中间产物，并等待用户确认。\n- Step 4 / evaluation：Step 4 必须围绕“评估管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / agentic-tracing：Step 5 必须围绕“智能体追踪系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/raga-ai-hub/RagaAI-Catalyst\n- https://github.com/raga-ai-hub/RagaAI-Catalyst#readme\n- ragaai_catalyst/ragaai_catalyst.py\n- examples/all_llm_provider/config.py\n- examples/custom_agents/travel_agent/config.py\n- ragaai_catalyst/__init__.py\n- ragaai_catalyst/dataset.py\n- docs/dataset_management.md\n- ragaai_catalyst/evaluation.py\n- ragaai_catalyst/experiment.py\n- ragaai_catalyst/tracers/agentic_tracing/__init__.py\n- ragaai_catalyst/tracers/agentic_tracing/tracers/base.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 RagaAI-Catalyst 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Standardizing Agent Commerce: Merxex Integration Proposal（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264）；github/github_issue: Authorization receipts for agent traces — signed governance proof per tr（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263）；github/github_issue: Tamper-proof audit logs to complement observability traces（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/259）；github/github_issue: 🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256）；github/github_issue: Integration: Agent-SRE Reliability Layer for AI Agent Monitoring（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253）；github/github_issue: Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure t（https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250）；github/github_release: 2.2.4（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4）；github/github_release: 2.2.3（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3）；github/github_release: 2.2.1（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1）；github/github_release: 2.1.7.1（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1）；github/github_release: 2.1.6.4（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4）；github/github_release: 2.1.6.2（https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Standardizing Agent Commerce: Merxex Integration Proposal",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264"
},
{
"kind": "github_issue",
"source": "github",
"title": "Authorization receipts for agent traces — signed governance proof per tr",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263"
},
{
"kind": "github_issue",
"source": "github",
"title": "Tamper-proof audit logs to complement observability traces",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/259"
},
{
"kind": "github_issue",
"source": "github",
"title": "🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256"
},
{
"kind": "github_issue",
"source": "github",
"title": "Integration: Agent-SRE Reliability Layer for AI Agent Monitoring",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253"
},
{
"kind": "github_issue",
"source": "github",
"title": "Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure t",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250"
},
{
"kind": "github_release",
"source": "github",
"title": "2.2.4",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4"
},
{
"kind": "github_release",
"source": "github",
"title": "2.2.3",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3"
},
{
"kind": "github_release",
"source": "github",
"title": "2.2.1",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1"
},
{
"kind": "github_release",
"source": "github",
"title": "2.1.7.1",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1"
},
{
"kind": "github_release",
"source": "github",
"title": "2.1.6.4",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4"
},
{
"kind": "github_release",
"source": "github",
"title": "2.1.6.2",
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "Python 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",
"effort": "安装已验证",
"forks": 3607,
"icon": "search",
"name": "RagaAI-Catalyst 能力包",
"risk": "可发布",
"slug": "ragaai-catalyst",
"stars": 16156,
"tags": [
"知识检索",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "blue",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/raga-ai-hub/RagaAI-Catalyst 项目说明书\n\n生成时间：2026-05-21 05:24:17 UTC\n\n## 目录\n\n- [安装与快速开始](#installation)\n- [配置与认证](#configuration)\n- [项目管理](#project-management)\n- [数据集管理](#dataset-management)\n- [评估管理](#evaluation)\n- [提示词管理](#prompt-management)\n- [智能体追踪系统](#agentic-tracing)\n- [追踪器类型与框架支持](#tracer-types)\n- [合成数据生成](#synthetic-data)\n- [安全护栏管理](#guardrails)\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[配置与认证](#configuration), [项目管理](#project-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/requirements.txt)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n \n\n# 安装与快速开始\n\n## 概述\n\nRagaAI Catalyst 是一个企业级 MLOps 和 LLM 应用监控平台，提供完整的模型生命周期管理能力。该平台支持项目创建、数据集管理、应用追踪、提示词管理、合成数据生成、护栏管理和红队测试等核心功能。资料来源：[README.md:1-15]()\n\n本页面将指导用户完成 RagaAI Catalyst SDK 的完整安装流程、认证配置以及基础使用示例，帮助开发者快速上手使用该平台进行 LLM 应用的开发与监控。\n\n---\n\n## 安装前置条件\n\n### 系统要求\n\n| 要求类型 | 最低版本 |\n|---------|---------|\n| Python | 3.10+ |\n| pip | 最新版本 |\n| 内存 | 4GB+ |\n| 网络 | 需要访问 RagaAI Catalyst 服务端点 |\n\n### 依赖环境\n\nRagaAI Catalyst SDK 依赖以下核心包：\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|-----|\n| openai | >=1.0.0 | OpenAI API 集成 |\n| pandas | >=2.0.0 | 数据处理 |\n| opentelemetry-api | >=1.25.0 | 追踪 instrumentation |\n| opentelemetry-sdk | >=1.25.0 | SDK 核心功能 |\n| litellm | >=1.61.15 | 多模型调用支持 |\n\n完整依赖列表请参考 `requirements.txt` 文件。资料来源：[requirements.txt:1-50]()\n\n---\n\n## 安装方式\n\n### 方式一：pip 直接安装（推荐）\n\n使用 pip 包管理器直接安装是最简便的方式：\n\n```bash\npip install ragaai-catalyst\n```\n\n资料来源：[README.md:20]()\n\n### 方式二：从源码安装\n\n如需安装最新开发版本或进行二次开发，可从源码安装：\n\n```bash\ngit clone https://github.com/raga-ai-hub/RagaAI-Catalyst.git\ncd RagaAI-Catalyst\npip install -e .\n```\n\n### 方式三：开发环境安装\n\n如果需要安装包含所有可选依赖的开发环境：\n\n```bash\npip install -r requirements.txt\n```\n\n资料来源：[tests_requirements.txt:1-15]()\n\n---\n\n## 认证配置\n\n### 获取 API 密钥\n\n使用 RagaAI Catalyst 前必须完成认证配置。获取密钥的步骤如下：\n\n1. 登录 [RagaAI Catalyst 平台](https://catalyst.raga.ai/)\n2. 进入 **Profile Settings** → **Authentication**\n3. 点击 **Generate New Key** 创建新的访问密钥\n4. 复制生成的 **Access Key** 和 **Secret Key**\n\n资料来源：[README.md:25-35]()\n\n\n\n### 初始化 SDK\n\n在 Python 代码中初始化 RagaAICatalyst 客户端：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\", # 替换为您的访问密钥\n secret_key=\"YOUR_SECRET_KEY\", # 替换为您的密钥\n base_url=\"BASE_URL\" # 替换为服务基地址\n)\n```\n\n资料来源：[README.md:36-45]()\n\n---\n\n## 快速开始工作流\n\n以下流程图展示了使用 RagaAI Catalyst 的基本工作顺序：\n\n```mermaid\ngraph TD\n A[安装 ragaai-catalyst] --> B[配置认证密钥]\n B --> C[创建项目]\n C --> D[添加数据集]\n D --> E[集成追踪功能]\n E --> F[运行应用]\n F --> G[查看评估结果]\n \n style A fill:#e1f5fe\n style G fill:#c8e6c9\n```\n\n---\n\n## 创建第一个项目\n\n### 项目创建示例\n\n创建项目时需要指定项目名称和用例类型：\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"Test-RAG-App-1\",\n usecase=\"Chatbot\" # 可选值: Chatbot, Q/A, Others, Agentic Application\n)\n\n# 获取可用用例列表\nprint(catalyst.project_use_cases())\n\n# 列出所有项目\nprojects = catalyst.list_projects()\nprint(projects)\n```\n\n资料来源：[README.md:50-65]()\n\n### 支持的用例类型\n\n| 用例类型 | 说明 |\n|---------|-----|\n| Chatbot | 聊天机器人应用 |\n| Q/A | 问答系统 |\n| Others | 其他类型应用 |\n| Agentic Application | 智能体应用 |\n\n---\n\n## 数据集管理\n\n### 创建数据集\n\n支持从 CSV 文件创建数据集，需要定义 schema mapping：\n\n```python\nfrom ragaai_catalyst import Dataset\n\n# 初始化数据集管理器\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 从 CSV 文件创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"MyDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n\n# 查看数据集 schema\nprint(dataset_manager.get_schema_mapping())\n```\n\n资料来源：[README.md:70-90]()\n\n### Schema Mapping 配置说明\n\n| Schema 元素 | 说明 |\n|------------|-----|\n| Query/prompt | 用户输入查询 |\n| response | 模型响应 |\n| Context | 上下文信息 |\n| expectedResponse | 期望的标准响应 |\n\n---\n\n## 应用追踪配置\n\n### 自动注入追踪\n\n支持多种智能体框架的自动追踪：\n\n```python\nfrom ragaai_catalyst import init_tracing, Tracer\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\" # 选择对应的框架类型\n)\n\n# 启用自动注入\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[quickstart.md:30-45]()\n\n### 支持的追踪器类型\n\n| 追踪器类型 | 框架支持 |\n|-----------|---------|\n| agentic/langgraph | LangGraph |\n| agentic/langchain | LangChain |\n| agentic/smolagents | SmoLAgents |\n| agentic/openai_agents | OpenAI Agents |\n| agentic/llamaindex | LlamaIndex |\n| agentic/haystack | Haystack |\n| agentic/crewai | CrewAI |\n| rag/langchain | RAG + LangChain |\n\n资料来源：[quickstart.md:55-65]()\n\n### 自定义追踪\n\n```python\nfrom ragaai_catalyst import Tracer\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"tracer_type\"\n)\n\n# 方式一：使用 with 语句\nwith tracer():\n # 您的应用代码\n pass\n\n# 方式二：手动控制\ntracer.start()\n# 您的应用代码\ntracer.stop()\n\n# 查看上传状态\nprint(tracer.get_upload_status())\n```\n\n---\n\n## 提示词管理\n\n### PromptManager 使用\n\n```python\nfrom ragaai_catalyst import PromptManager\n\n# 初始化提示词管理器\nprompt_manager = PromptManager(project_name=\"Test-RAG-App-1\")\n\n# 列出可用提示词\nprompts = prompt_manager.list_prompts()\nprint(\"Available prompts:\", prompts)\n\n# 获取指定提示词\nprompt = prompt_manager.get_prompt(\"your_prompt_name\")\n\n# 获取提示词内容\nprompt_content = prompt.get_prompt_content()\nprint(\"prompt_content:\", prompt_content)\n\n# 获取提示词变量\nvariables = prompt.get_variables()\nprint(\"variables:\", variables)\n\n# 编译提示词\ncompiled_prompt = prompt.compile(\n query=\"What's the weather?\",\n context=\"sunny\",\n llm_response=\"It's sunny today\"\n)\n```\n\n资料来源：[README.md:120-145]()\n\n---\n\n## 示例代码\n\n### SmoLAgents 示例\n\n安装示例依赖后运行：\n\n```bash\npip install -r requirements.txt\n```\n\n```python\nfrom most_upvoted_paper import main\n\n# 运行论文摘要管道\nmain()\n```\n\n该示例展示如何使用 SmoLAgents 框架下载论文并生成摘要。资料来源：[examples/smolagents/most_upvoted_paper/README.md:1-25]()\n\n### CrewAI 示例\n\n完整的 CrewAI 应用追踪示例：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom crewai import Agent, Task, Crew, Process\nfrom crewai.tools import tool\n\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'), \n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'), \n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 定义 CrewAI agents 和 tasks...\ncrew = Crew(\n agents=[brainstormer, outliner, writer],\n tasks=[brainstorm_task, outline_task, writing_task],\n process=Process.sequential,\n verbose=True\n)\n\nresult = crew.kickoff()\n```\n\n---\n\n## 常见问题\n\n### 环境变量配置\n\n建议使用 `.env` 文件管理敏感信息：\n\n```bash\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key\nRAGAAI_CATALYST_BASE_URL=your_base_url\nRAGAAI_PROJECT_NAME=your_project_name\nRAGAAI_DATASET_NAME=your_dataset_name\n```\n\n### 导入问题\n\n如遇到导入错误，请确保：\n\n1. 已正确安装 `ragaai-catalyst` 包\n2. Python 版本符合要求（3.10+）\n3. 所有依赖包已正确安装\n\n---\n\n## 下一步\n\n完成安装和快速开始后，您可以：\n\n- 深入了解[评估框架](./evaluation_framework.md)的使用\n- 探索[红队测试](./red_teaming.md)功能\n- 配置[护栏管理](./guardrails.md)规则\n- 学习[合成数据生成](./synthetic_data.md)技术\n\n---\n\n\n\n## 配置与认证\n\n### 相关页面\n\n相关主题：[安装与快速开始](#installation), [智能体追踪系统](#agentic-tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/ragaai_catalyst.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 配置与认证\n\n## 概述\n\nRagaAI Catalyst 的配置与认证系统是整个平台的基础模块，负责管理用户身份验证、凭证存储以及与后端服务的安全通信。所有使用 RagaAI Catalyst 功能之前必须完成正确的配置和身份认证。\n\n核心认证流程通过 `RagaAICatalyst` 类实现，该类封装了所有与平台服务的交互逻辑，支持通过环境变量或直接传入参数两种方式进行配置。\n\n## 认证凭证获取\n\n### 获取步骤\n\n1. 登录 [RagaAI Catalyst](https://catalyst.raga.ai/) 账户\n2. 进入 **Profile Settings** → **Authentication** 页面\n3. 点击 **Generate New Key** 生成新的访问密钥\n\n认证成功后，用户将获得以下凭证信息：\n\n| 凭证类型 | 用途 | 必要性 |\n|---------|------|--------|\n| Access Key | 标识用户身份 | 必须 |\n| Secret Key | 验证用户身份 | 必须 |\n| Base URL | API 端点地址 | 必须 |\n\n## SDK 初始化配置\n\n### 基本初始化\n\n使用 `RagaAICatalyst` 类进行 SDK 初始化是最基础的配置方式：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\", # 用户访问密钥\n secret_key=\"YOUR_SECRET_KEY\", # 用户密钥\n base_url=\"BASE_URL\" # 服务端点\n)\n```\n\n### 环境变量配置\n\n在生产环境中，推荐使用环境变量存储敏感凭证，避免硬编码：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst\n\n# 加载 .env 文件中的环境变量\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n```\n\n典型 `.env` 文件配置：\n\n```env\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key_here\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key_here\nRAGAAI_CATALYST_BASE_URL=https://api.raga.ai/catalyst\n```\n\n## 追踪功能配置\n\n### Tracer 初始化\n\n追踪系统需要单独配置 `Tracer` 类，与主 SDK 配合使用：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 1. 初始化主 SDK\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 2. 初始化追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\" # 支持多种追踪类型\n)\n\n# 3. 启用自动追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### Tracer 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| project_name | string | 必填 | 项目名称 |\n| dataset_name | string | 必填 | 数据集名称 |\n| trace_name | string | None | 追踪名称 |\n| tracer_type | string | None | 追踪器类型 |\n| timeout | int | 120 | 超时时间（秒） |\n| update_llm_cost | bool | True | 是否更新模型成本 |\n| max_upload_workers | int | 30 | 最大上传并发数 |\n\n### 自动仪表化配置\n\n可通过 `auto_instrumentation` 参数控制各组件的自动追踪：\n\n```python\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\",\n auto_instrumentation={\n 'llm': True, # LLM 调用追踪\n 'tool': True, # 工具调用追踪\n 'agent': True, # Agent 追踪\n 'user_interaction': True, # 用户交互追踪\n 'file_io': True, # 文件操作追踪\n 'network': True, # 网络请求追踪\n 'custom': True # 自定义事件追踪\n }\n)\n```\n\n## 支持的追踪器类型\n\nRagaAI Catalyst 支持多种框架的追踪集成：\n\n| tracer_type | 框架 | 说明 |\n|-------------|------|------|\n| agentic/langgraph | LangGraph | 图结构工作流追踪 |\n| agentic/langchain | LangChain | LangChain 框架追踪 |\n| agentic/smolagents | SmolAgents | 轻量级 Agent 追踪 |\n| agentic/openai_agents | OpenAI Agents | OpenAI Agent SDK |\n| agentic/llamaindex | LlamaIndex | 索引和查询追踪 |\n| agentic/haystack | Haystack | NLP 管道追踪 |\n| agentic/crewai | CrewAI | 多 Agent 协作追踪 |\n| rag/langchain | LangChain RAG | RAG 应用追踪 |\n\n## 配置架构\n\n```mermaid\ngraph TD\n A[应用程序] --> B[环境变量 / .env]\n B --> C[RagaAICatalyst 初始化]\n C --> D[认证服务验证]\n D --> E{验证结果}\n E -->|成功| F[创建项目 / 管理数据集]\n E -->|失败| G[认证错误]\n F --> H[Tracer 初始化]\n H --> I[init_tracing 启用追踪]\n I --> J[追踪数据上传]\n \n K[手动配置] --> C\n style G fill:#ffcccc\n```\n\n## 典型配置流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant App as 应用程序\n participant Env as 环境变量\n participant SDK as RagaAICatalyst\n participant API as RagaAI API\n \n User->>API: 1. 生成认证密钥\n API->>User: 返回 access_key, secret_key\n User->>Env: 2. 配置环境变量\n App->>Env: 3. 加载环境变量\n App->>SDK: 4. 初始化 SDK\n SDK->>API: 5. 验证凭证\n API-->>SDK: 验证成功\n SDK-->>App: SDK 实例就绪\n App->>SDK: 6. 创建 Tracer\n SDK->>API: 7. 注册追踪器\n App->>SDK: 8. 调用 init_tracing\n SDK->>API: 9. 启用数据采集\n```\n\n## 项目级配置\n\n除了全局 SDK 配置外，RagaAI Catalyst 还支持项目级别的配置管理：\n\n```python\n# 创建项目时指定用例类型\nproject = catalyst.create_project(\n project_name=\"My-RAG-App\",\n usecase=\"Q/A\" # 可选值: Chatbot, Q/A, Others, Agentic Application\n)\n\n# 查看可用的用例类型\nprint(catalyst.project_use_cases())\n\n# 列出所有项目\nprojects = catalyst.list_projects()\n```\n\n## 数据集配置\n\n数据集管理同样需要正确的项目配置：\n\n```python\nfrom ragaai_catalyst import Dataset\n\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 从 CSV 创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"MyDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n```\n\n## 安全建议\n\n| 建议 | 说明 |\n|------|------|\n| 使用环境变量 | 避免在代码中硬编码敏感凭证 |\n| 使用 .env 文件 | 使用 `python-dotenv` 管理环境配置 |\n| 定期轮换密钥 | 定期更换 Access Key 和 Secret Key |\n| 最小权限原则 | 仅授予必要的 API 访问权限 |\n| 密钥存储 | 生产环境使用密钥管理服务（如 AWS Secrets Manager） |\n\n## 常见错误处理\n\n认证配置过程中可能遇到的常见错误：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| InvalidCredentials | 密钥格式错误或已过期 | 重新生成认证密钥 |\n| NetworkError | 网络连接问题 | 检查网络代理和防火墙设置 |\n| Unauthorized | 密钥权限不足 | 检查 API 密钥的访问范围 |\n| TimeoutError | 服务响应超时 | 增加 timeout 参数值 |\n\n## 完整示例\n\n以下是一个完整的配置与认证示例：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 加载环境变量\nload_dotenv()\n\n# 初始化主 SDK\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\"\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 创建项目\nproject = catalyst.create_project(\n project_name=\"Test-Project\",\n usecase=\"Agentic Application\"\n)\n```\n\n## 相关文档\n\n- [快速开始指南](quickstart.md) - 完整的快速入门教程\n- [追踪管理](./tracing.md) - 详细的追踪功能说明\n- [评估框架](./evaluation.md) - 评估功能配置\n- [项目与数据集管理](./project_dataset.md) - 项目和数据集操作\n\n---\n\n\n\n## 项目管理\n\n### 相关页面\n\n相关主题：[数据集管理](#dataset-management), [评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n \n\n# 项目管理\n\n## 概述\n\n项目管理是 RagaAI Catalyst 平台的核心功能模块，用于组织和管理 AI 应用的全生命周期。通过项目管理功能，用户可以创建不同类型的 AI 应用项目、管理相关数据集、配置追踪器、运行评估任务以及执行红队测试。\n\nRagaAI Catalyst 的项目管理采用分层架构设计，核心入口为 `RagaAICatalyst` 类，通过该类可以访问所有项目管理相关功能。资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 核心架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[RagaAICatalyst 客户端]\n B --> C[项目管理]\n B --> D[数据集管理]\n B --> E[追踪管理]\n B --> F[评估管理]\n B --> G[提示词管理]\n B --> H[红队测试]\n \n C --> I[创建项目]\n C --> J[列举项目]\n C --> K[使用案例配置]\n \n D --> L[CSV 上传]\n D --> M[DataFrame 上传]\n D --> N[JSONL 上传]\n \n E --> O[LangGraph 追踪]\n E --> P[LangChain 追踪]\n E --> Q[其他框架追踪]\n```\n\n### 客户端初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Env as 环境变量\n participant Catalyst as RagaAICatalyst\n \n User->>Env: 设置认证凭证\n User->>Catalyst: 初始化客户端\n Catalyst->>Catalyst: 验证凭证\n Catalyst-->>User: 返回客户端实例\n```\n\n## 客户端初始化\n\n### 基本配置\n\n使用 RagaAI Catalyst 之前，必须先初始化 `RagaAICatalyst` 客户端实例。客户端支持通过环境变量或直接传入参数两种方式进行配置。资料来源：[README.md:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n```\n\n### 环境变量配置方式\n\n在实际项目中，推荐使用环境变量方式配置认证信息，便于管理敏感凭证。资料来源：[examples/custom_agents/travel_agent/config.py:1-20](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n### 初始化参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| access_key | str | 是 | 访问密钥，从 RagaAI Catalyst 平台获取 |\n| secret_key | str | 是 | 秘密密钥，从 RagaAI Catalyst 平台获取 |\n| base_url | str | 是 | API 基础 URL，根据部署环境配置 |\n\n### 获取认证密钥\n\n1. 登录 RagaAI Catalyst 平台 (https://catalyst.raga.ai/)\n2. 进入个人资料设置 (Profile Settings)\n3. 选择身份验证 (Authentication) 选项卡\n4. 点击生成新密钥 (Generate New Key) 创建访问密钥和秘密密钥\n\n资料来源：[quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n\n## 项目创建与管理\n\n### 创建新项目\n\n使用 `create_project` 方法创建新项目，需要指定项目名称和用例类型。资料来源：[README.md:35-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"Test-RAG-App-1\",\n usecase=\"Chatbot\" # 用例类型\n)\n\n# 获取可用用例列表\nprint(catalyst.project_use_cases())\n```\n\n### 支持的用例类型\n\n| 用例类型 | 说明 | 适用场景 |\n|----------|------|----------|\n| Chatbot | 聊天机器人 | 对话式 AI 应用 |\n| Q/A | 问答系统 | 知识问答、RAG 应用 |\n| Others | 其他 | 自定义 AI 应用 |\n| Agentic Application | 代理应用 | 自主代理、多步骤任务 |\n\n### 列举项目\n\n```python\n# 列出所有项目\nprojects = catalyst.list_projects()\nprint(projects)\n```\n\n## 追踪器与项目集成\n\n项目管理与追踪系统紧密集成，每个项目可以配置专属的追踪器用于监控应用行为。资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-25](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n\n### 追踪器初始化\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化 Catalyst 客户端\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'), \n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'), \n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建项目级追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### 追踪器类型对照表\n\n| tracer_type 参数 | 支持框架 | 说明 |\n|------------------|----------|------|\n| agentic/langgraph | LangGraph | LangGraph 框架追踪 |\n| agentic/langchain | LangChain | LangChain 框架追踪 |\n| agentic/smolagents | SmolAgents | SmolAgents 框架追踪 |\n| agentic/openai_agents | OpenAI Agents | OpenAI Agents SDK 追踪 |\n| agentic/llamaindex | LlamaIndex | LlamaIndex 框架追踪 |\n| agentic/haystack | Haystack | Haystack 框架追踪 |\n| agentic/crewai | CrewAI | CrewAI 框架追踪 |\n\n资料来源：[examples/langgraph/personal_research_assistant/research_assistant.py:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n\n### 完整配置示例\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\nload_dotenv()\n\ndef initialize_tracing():\n \"\"\"初始化追踪配置\"\"\"\n catalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n )\n\n tracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\",\n )\n\n init_tracing(catalyst=catalyst, tracer=tracer)\n return tracer\n```\n\n## 项目相关组件\n\n### 组件关系图\n\n```mermaid\ngraph LR\n A[项目 Project] --> B[数据集 Dataset]\n A --> C[追踪器 Tracer]\n A --> D[评估 Evaluation]\n A --> E[提示词 Prompt]\n A --> F[红队测试]\n \n B --> B1[Schema Mapping]\n B --> B2[数据源]\n \n C --> C1[追踪数据]\n C --> C2[执行记录]\n \n D --> D1[评估指标]\n D --> D2[评估结果]\n```\n\n### 各组件功能说明\n\n| 组件名称 | 功能描述 | 主要方法 |\n|----------|----------|----------|\n| Dataset | 数据集管理 | create_from_csv, get_schema_mapping |\n| Tracer | 执行追踪 | start, stop, get_upload_status |\n| Evaluation | 模型评估 | add_metrics, get_status, get_results |\n| PromptManager | 提示词管理 | list_prompts, get_prompt, compile |\n| RedTeaming | 红队测试 | run, detectors |\n\n## 环境变量配置\n\n### 必需环境变量\n\n| 环境变量名 | 说明 | 示例值 |\n|------------|------|--------|\n| RAGAAI_CATALYST_ACCESS_KEY | 访问密钥 | sk-xxx |\n| RAGAAI_CATALYST_SECRET_KEY | 秘密密钥 | sk-xxx |\n| RAGAAI_CATALYST_BASE_URL | API 地址 | https://api.catalyst.raga.ai |\n| RAGAAI_PROJECT_NAME | 项目名称 | my-project |\n| RAGAAI_DATASET_NAME | 数据集名称 | my-dataset |\n\n### .env 文件配置示例\n\n```bash\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key_here\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key_here\nRAGAAI_CATALYST_BASE_URL=https://api.catalyst.raga.ai\nRAGAAI_PROJECT_NAME=Test-Project\nRAGAAI_DATASET_NAME=Test-Dataset\n```\n\n## 典型使用流程\n\n### 完整项目生命周期流程\n\n```mermaid\ngraph TD\n A[初始化客户端] --> B[创建项目]\n B --> C[配置用例类型]\n C --> D[创建数据集]\n D --> E[初始化追踪器]\n E --> F[开发应用代码]\n F --> G[运行评估]\n G --> H{评估结果}\n H -->|通过| I[部署上线]\n H -->|失败| J[问题修复]\n J --> F\n```\n\n### 分步操作示例\n\n**步骤 1: 初始化和认证**\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n**步骤 2: 创建和管理项目**\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"My-RAG-Application\",\n usecase=\"Q/A\"\n)\n\n# 查看可用用例\nuse_cases = catalyst.project_use_cases()\n\n# 列举所有项目\nall_projects = catalyst.list_projects()\n```\n\n**步骤 3: 集成追踪功能**\n\n```python\nfrom ragaai_catalyst import init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ntracer = Tracer(\n project_name=\"My-RAG-Application\",\n dataset_name=\"production-traces\",\n tracer_type=\"agentic/langgraph\",\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n## 最佳实践\n\n### 1. 项目组织建议\n\n- 按业务线或应用类型划分项目\n- 为每个项目配置独立的数据集和追踪器\n- 使用清晰的项目命名规范\n\n### 2. 认证安全建议\n\n- 敏感凭证使用环境变量管理\n- 避免在代码中硬编码密钥\n- 定期轮换访问密钥\n\n### 3. 追踪配置建议\n\n- 根据应用框架选择正确的 tracer_type\n- 为生产环境和开发环境使用不同的数据集\n- 定期检查追踪数据上传状态\n\n## 依赖要求\n\n项目管理的 Python 依赖已包含在主包中，核心依赖包括：\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|----------|------|\n| openai | >=1.0.0 | OpenAI API 集成 |\n| pandas | >=2.0.0 | 数据处理 |\n| dotenv | 最新版 | 环境变量管理 |\n\n额外测试依赖见 [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n\n## 常见问题\n\n### Q: 如何获取认证密钥？\n\n登录 RagaAI Catalyst 平台，进入 Profile Settings → Authentication，点击 Generate New Key 获取。\n\n### Q: tracer_type 有哪些可选值？\n\n支持 agentic/langgraph、agentic/langchain、agentic/smolagents、agentic/openai_agents、agentic/llamaindex、agentic/haystack 等类型。\n\n### Q: 项目和数据集是什么关系？\n\n一个项目可以包含多个数据集，数据集用于存储评估用的测试数据和追踪记录。\n\n---\n\n\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[项目管理](#project-management), [评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 数据集管理\n\n## 概述\n\nRagaAI Catalyst 的数据集管理模块为用户提供了统一的数据集创建、查询和元数据管理能力。该模块支持从 CSV 文件、DataFrame 或 JSONL 文件导入数据集，并提供了灵活的模式映射（Schema Mapping）功能，使用户能够将数据列映射到系统定义的标准模式元素。\n\n数据集管理在 RagaAI Catalyst 平台中扮演着数据入口的角色，是后续追踪（Tracing）和评估（Evaluation）功能的基础前提。只有在项目下创建了有效的数据集，用户才能配置追踪器捕获应用行为，或运行评估指标分析应用性能。\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 核心类与导入\n\n数据集管理的核心功能通过 `Dataset` 类实现，该类封装了所有与数据集操作相关的接口。\n\n```python\nfrom ragaai_catalyst import Dataset\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 初始化 Dataset 管理器\n\n在使用任何数据集操作之前，需要先初始化 `Dataset` 管理器实例。初始化时必须指定项目名称，以便在对应的项目上下文中管理数据集。\n\n```python\ndataset_manager = Dataset(project_name=\"project_name\")\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 主要功能\n\n### 列出已有数据集\n\n用户可以通过 `list_datasets()` 方法查看指定项目下所有已创建的数据集。\n\n```python\ndatasets = dataset_manager.list_datasets()\nprint(\"Existing Datasets:\", datasets)\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n### 从 CSV 文件创建数据集\n\n`create_from_csv()` 方法允许用户从本地 CSV 文件导入数据创建数据集。该方法需要提供文件路径、数据集名称以及列映射配置。\n\n```python\ndataset_manager.create_from_csv(\n csv_path='path/to/your.csv',\n dataset_name='MyDataset',\n schema_mapping={'column1': 'schema_element1', 'column2': 'schema_element2'}\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md) 和 [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n### 获取模式映射\n\n创建数据集时定义的模式映射可以通过 `get_schema_mapping()` 方法查询，用于验证数据列与系统模式元素的对应关系。\n\n```python\nprint(dataset_manager.get_schema_mapping())\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 模式映射（Schema Mapping）\n\n模式映射是数据集创建过程中的核心配置项，用于将用户数据中的列名映射到 RagaAI Catalyst 平台定义的标准化模式元素。\n\n### 标准模式元素\n\n根据评估框架的使用示例，典型的模式映射结构如下：\n\n| 用户数据列 | 标准模式元素 | 说明 |\n|------------|--------------|------|\n| Query / prompt | 提示词 | 用户的输入查询 |\n| response | 响应 | 模型的返回结果 |\n| Context / context | 上下文 | RAG 应用的检索上下文 |\n| expectedResponse / expected_response | 期望响应 | 用于评估的参考答案 |\n\n```python\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 数据集管理流程\n\n```mermaid\ngraph TD\n A[初始化 Dataset 管理器] --> B{数据源类型}\n B -->|CSV 文件| C[调用 create_from_csv]\n B -->|DataFrame| D[调用 create_from_dataframe]\n B -->|JSONL 文件| E[调用 create_from_jsonl]\n C --> F[定义 schema_mapping]\n D --> F\n E --> F\n F --> G[创建数据集]\n G --> H[验证模式映射]\n H --> I[数据集可用于评估和追踪]\n```\n\n## 在评估框架中的使用\n\n数据集创建完成后，可以与评估框架集成，用于运行各种评估指标。以下是数据集在评估流程中的典型使用方式：\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 使用已创建的数据集初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Project_Name\",\n dataset_name=\"MyDataset\"\n)\n\n# 定义与数据集对应的 schema_mapping\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n\n# 添加评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\", \"threshold\": {\"gte\": 0.232323}},\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 在追踪框架中的使用\n\n数据集同样用于追踪框架，用于存储和检索应用运行过程中的追踪记录：\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 最佳实践\n\n1. **命名规范**：数据集名称应具有描述性，便于在项目内识别不同数据集的用途\n2. **模式映射一致性**：确保 schema_mapping 在数据集创建和评估配置中保持一致\n3. **CSV 文件格式**：确保 CSV 文件编码为 UTF-8，且列名与 schema_mapping 的键完全匹配\n4. **先创建后使用**：在进行评估或追踪之前，确保数据集已成功创建并上传\n\n---\n\n\n\n## 评估管理\n\n### 相关页面\n\n相关主题：[数据集管理](#dataset-management), [项目管理](#project-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/evaluation.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/evaluation.py)\n- [ragaai_catalyst/experiment.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/experiment.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [Quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/Quickstart.md)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n \n\n# 评估管理\n\n评估管理是 RagaAI Catalyst 平台的核心功能模块之一，旨在为 RAG（检索增强生成）应用提供标准化的评估框架。该模块允许开发者对 LLM 应用进行系统化评估，通过可配置的评估指标验证应用的实际表现。\n\n## 功能概述\n\n评估管理模块提供以下核心能力：\n\n| 功能 | 描述 |\n|------|------|\n| 评估引擎初始化 | 创建与管理评估实验 |\n| 指标管理 | 添加、配置和查看可用评估指标 |\n| 结果获取 | 获取评估状态与结果数据 |\n| 模式映射 | 支持自定义数据集字段与评估框架的映射 |\n\n## 核心组件\n\n### Evaluation 类\n\n`Evaluation` 类是评估管理的入口点，负责协调整个评估流程。\n\n```python\nfrom ragaai_catalyst import Evaluation\n\nevaluation = Evaluation(\n project_name=\"项目名称\",\n dataset_name=\"数据集名称\"\n)\n```\n\n### 构造函数参数\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| project_name | str | 是 | 项目名称，用于组织和标识评估实验 |\n| dataset_name | str | 是 | 数据集名称，指定用于评估的数据源 |\n\n## 评估工作流程\n\n```mermaid\ngraph TD\n A[初始化评估引擎] --> B[定义模式映射]\n B --> C[添加评估指标]\n C --> D[执行评估]\n D --> E[获取评估状态]\n E --> F{状态检查}\n F -->|完成| G[获取评估结果]\n F -->|进行中| E\n```\n\n## 使用方法\n\n### 基础用法\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Test-RAG-App-1\",\n dataset_name=\"MyDataset\"\n)\n\n# 获取可用指标列表\navailable_metrics = evaluation.list_metrics()\nprint(\"可用指标:\", available_metrics)\n```\n\n### 配置评估指标\n\n定义模式映射，将数据集列映射到评估框架的标准字段：\n\n```python\n# 定义模式映射\nschema_mapping = {\n 'Query': 'prompt', # 用户查询字段\n 'response': 'response', # 模型响应字段\n 'Context': 'context', # 上下文/检索结果字段\n 'expectedResponse': 'expected_response' # 期望响应字段\n}\n\n# 添加评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.5}\n },\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n },\n {\n \"name\": \"AnswerRelevancy\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.7}\n },\n \"column_name\": \"Relevancy_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n### 指标配置参数说明\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| name | str | 指标名称（如 Faithfulness、AnswerRelevancy） |\n| config | dict | 指标配置，包含模型、提供商和阈值设置 |\n| config.model | str | 用于评估的 LLM 模型 |\n| config.provider | str | 模型提供商（如 openai、anthropic） |\n| config.threshold | dict | 阈值条件，支持 gte（大于等于）、lte（小于等于）等操作符 |\n| column_name | str | 结果列名，用于标识评估结果 |\n| schema_mapping | dict | 数据集字段映射配置 |\n\n### 获取评估结果\n\n```python\n# 获取评估状态\nstatus = evaluation.get_status()\nprint(f\"评估状态: {status}\")\n\n# 获取评估结果\nresults = evaluation.get_results()\nprint(f\"评估结果: {results}\")\n```\n\n## 模式映射配置\n\n模式映射是连接数据集与评估框架的关键配置，用于指定数据集中各字段的语义角色。\n\n### 标准字段映射\n\n| 框架字段 | 描述 | 示例数据列名 |\n|----------|------|--------------|\n| Query | 用户输入/问题 | prompt, question, input |\n| response | LLM 生成的回答 | response, answer, output |\n| Context | 检索到的上下文内容 | context, retrieved_docs |\n| expectedResponse | 参考标准答案 | expected_response, ground_truth |\n\n### 自定义映射示例\n\n```python\nschema_mapping = {\n 'Query': 'user_question',\n 'response': 'assistant_reply',\n 'Context': 'retrieved_content',\n 'expectedResponse': 'correct_answer'\n}\n\nevaluation.add_metrics(\n metrics=[{\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\"},\n \"column_name\": \"faithfulness_score\",\n \"schema_mapping\": schema_mapping\n }]\n)\n```\n\n## 支持的评估指标\n\n根据代码结构，评估框架支持多种内置指标，开发者可以通过 `list_metrics()` 方法获取完整的指标列表。\n\n### 常用指标类型\n\n| 指标名称 | 用途 | 阈值示例 |\n|----------|------|----------|\n| Faithfulness | 评估回答对上下文的忠实度 | {\"gte\": 0.5} |\n| AnswerRelevancy | 评估回答与问题的相关性 | {\"gte\": 0.7} |\n| ContextPrecision | 评估检索上下文的精确度 | {\"gte\": 0.6} |\n| ContextRecall | 评估检索上下文的召回率 | {\"gte\": 0.8} |\n\n## 完整使用示例\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 1. 初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Product-RAG-Project\",\n dataset_name=\"Product-QA-Dataset\"\n)\n\n# 2. 查看可用指标\nprint(\"可用评估指标:\")\nprint(evaluation.list_metrics())\n\n# 3. 配置模式映射\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'llm_response',\n 'Context': 'retrieved_context',\n 'expectedResponse': 'ground_truth'\n}\n\n# 4. 添加多个评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.5}\n },\n \"column_name\": \"faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n },\n {\n \"name\": \"AnswerRelevancy\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.7}\n },\n \"column_name\": \"relevancy_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n\n# 5. 检查评估状态\nprint(f\"状态: {evaluation.get_status()}\")\n\n# 6. 获取评估结果\nprint(f\"结果: {evaluation.get_results()}\")\n```\n\n## 集成注意事项\n\n### 前置条件\n\n- 已创建项目并配置有效的认证凭证\n- 已上传包含必要字段的数据集\n- 确保数据集字段与模式映射配置匹配\n\n### 数据集要求\n\n评估数据集应包含以下字段：\n\n1. **prompt** - 用户查询文本\n2. **response** - LLM 生成的回答\n3. **context** - 相关的上下文或检索结果\n4. **expected_response** - 预期的正确答案（可选）\n\n### 错误处理\n\n```python\ntry:\n evaluation = Evaluation(\n project_name=\"NonExistentProject\",\n dataset_name=\"TestDataset\"\n )\n evaluation.add_metrics(metrics=[...])\nexcept Exception as e:\n print(f\"评估初始化失败: {e}\")\n```\n\n## 与其他模块的协作\n\n评估管理模块与其他 RagaAI Catalyst 组件的关系：\n\n```mermaid\ngraph LR\n A[项目] --> B[数据集]\n B --> C[评估管理]\n C --> D[评估指标]\n D --> E[评估结果]\n \n F[追踪管理] --> C\n G[提示词管理] --> C\n```\n\n评估结果可与追踪管理模块结合使用，实现端到端的 LLM 应用监控与优化。\n\n---\n\n\n\n## 提示词管理\n\n### 相关页面\n\n相关主题：[项目管理](#project-management), [合成数据生成](#synthetic-data)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [docs/prompt_management.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/prompt_management.md)\n- [ragaai_catalyst/prompt_manager.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/prompt_manager.py)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n \n\n# 提示词管理\n\n## 概述\n\n提示词管理（Prompt Management）是 RagaAI Catalyst 平台的核心功能模块之一，旨在帮助开发者高效地管理、存储、版本控制和编译提示词模板。该模块提供了统一的接口，使开发者能够在项目中灵活地使用提示词，并支持变量插值、版本管理和动态编译等功能。\n\n提示词管理的核心价值在于将提示词从业务代码中分离出来，实现提示词的集中管理和复用，从而提升应用程序的可维护性和灵活性。开发者可以通过 `PromptManager` 类与平台进行交互，完成提示词的查询、获取和编译等操作。\n\n## 核心组件\n\n### PromptManager 类\n\n`PromptManager` 是提示词管理的入口类，提供了完整的提示词生命周期管理功能。\n\n```python\nfrom ragaai_catalyst import PromptManager\n\n# 初始化 PromptManager\nprompt_manager = PromptManager(project_name=\"Test-RAG-App-1\")\n```\n\n**初始化参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| project_name | str | 是 | 项目名称，用于关联提示词所属的项目 |\n| dataset_name | str | 否 | 数据集名称，可用于特定场景的提示词管理 |\n\n资料来源：[README.md:1-15]()\n\n### Prompt 对象\n\n`Prompt` 对象代表一个具体的提示词模板，包含以下核心方法：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `get_variables()` | dict | 获取提示词中定义的变量列表 |\n| `get_prompt_content()` | str | 获取提示词的原始内容 |\n| `compile(**kwargs)` | dict | 使用指定变量编译提示词 |\n\n资料来源：[README.md:20-35]()\n\n## 功能特性\n\n### 列表查询功能\n\n#### 列出可用提示词\n\n通过 `list_prompts()` 方法可以获取项目下所有可用的提示词模板：\n\n```python\n# 列出所有可用提示词\nprompts = prompt_manager.list_prompts()\nprint(\"Available prompts:\", prompts)\n```\n\n该方法返回提示词名称列表，开发者可以根据实际需求选择合适的提示词进行使用。\n\n#### 获取特定提示词\n\n根据提示词名称获取提示词对象，支持获取最新版本或指定版本：\n\n```python\n# 获取默认版本提示词\nprompt = prompt_manager.get_prompt(prompt_name)\n\n# 获取指定版本提示词\nprompt = prompt_manager.get_prompt(prompt_name, version=\"v1\")\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt_name | str | 是 | 提示词名称 |\n| version | str | 否 | 提示词版本号，默认为最新版本 |\n\n资料来源：[README.md:15-25]()\n\n### 变量提取功能\n\n提示词通常包含动态变量，开发者可以通过 `get_variables()` 方法提取这些变量：\n\n```python\n# 获取提示词中的变量\nvariable = prompt.get_variables()\nprint(\"variable:\", variable)\n```\n\n该方法返回一个字典，包含提示词中定义的所有变量名称及其默认值（如果有）。\n\n### 提示词内容获取\n\n获取提示词的原始模板内容：\n\n```python\n# 获取提示词原始内容\nprompt_content = prompt.get_prompt_content()\nprint(\"prompt_content:\", prompt_content)\n```\n\n返回的 `prompt_content` 是模板字符串，其中包含变量占位符，通常使用 `{{variable_name}}` 或 `{variable_name}` 格式。\n\n### 提示词编译\n\n#### 基本编译\n\n使用 `compile()` 方法将变量值注入到提示词模板中：\n\n```python\n# 编译提示词\ncompiled_prompt = prompt.compile(\n query=\"What's the weather?\",\n context=\"sunny\",\n llm_response=\"It's sunny today\"\n)\nprint(\"Compiled prompt:\", compiled_prompt)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| **kwargs | Any | 是 | 提示词模板中定义的变量及其对应值 |\n\n#### 编译结果使用\n\n编译后的提示词可以直接用于 LLM 调用：\n\n```python\nimport openai\n\ndef get_openai_response(prompt):\n client = openai.OpenAI()\n response = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=prompt\n )\n return response.choices[0].message.content\n\n# 使用编译后的提示词获取响应\nresult = get_openai_response(compiled_prompt)\n```\n\n资料来源：[README.md:30-55]()\n\n## 工作流程\n\n### 标准使用流程\n\n```mermaid\ngraph TD\n A[初始化 PromptManager] --> B[列出可用提示词]\n B --> C[选择提示词名称]\n C --> D[获取提示词对象]\n D --> E[提取变量列表]\n E --> F[准备变量值]\n F --> G[编译提示词]\n G --> H[集成到 LLM 调用]\n H --> I[获取响应结果]\n```\n\n### 版本管理流程\n\n```mermaid\ngraph TD\n A[获取提示词] --> B{指定版本?}\n B -->|是| C[传入 version 参数]\n B -->|否| D[获取最新版本]\n C --> E[验证版本有效性]\n D --> E\n E --> F{版本存在?}\n F -->|是| G[返回提示词对象]\n F -->|否| H[抛出异常]\n```\n\n## 应用场景\n\n### 问答系统\n\n在问答系统中，提示词管理可以用于：\n\n- 管理不同类型的问答模板\n- 支持上下文注入\n- 处理多轮对话场景\n\n### RAG 应用\n\n在检索增强生成（RAG）应用中，提示词管理发挥着重要作用：\n\n- 管理检索上下文模板\n- 处理多文档场景\n- 支持自定义生成风格\n\n### Agent 应用\n\n对于 Agent 应用，提示词管理支持：\n\n- 工具调用指令模板\n- 系统提示词管理\n- 角色定义模板\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-80]()\n\n## 配置与集成\n\n### 环境配置\n\n提示词管理功能需要与 RagaAICatalyst 配合使用，需要配置以下凭证：\n\n```python\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\n# 从环境变量或配置文件获取凭证\naccess_key = os.getenv('RAGAAI_CATALYST_ACCESS_KEY')\nsecret_key = os.getenv('RAGAAI_CATALYST_SECRET_KEY')\nbase_url = os.getenv('RAGAAI_CATALYST_BASE_URL')\nproject_name = os.getenv('RAGAAI_PROJECT_NAME')\n```\n\n### 与追踪系统集成\n\n提示词管理可以与 RagaAI 的追踪系统无缝集成：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化催化剂实例\ncatalyst = RagaAICatalyst(\n access_key=access_key,\n secret_key=secret_key,\n base_url=base_url\n)\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=project_name,\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"agentic/langchain\"\n)\n\n# 启用自动追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/langchain/medical_rag/diagnosis_agent.py:1-35]()\n\n## 最佳实践\n\n### 提示词设计原则\n\n1. **变量命名清晰**：使用描述性的变量名称，便于理解和使用\n2. **版本控制**：为重要提示词添加版本号，便于追踪变更\n3. **模块化设计**：将复杂提示词拆分为可复用的模块\n4. **文档完善**：为提示词添加说明和示例\n\n### 性能优化\n\n1. **缓存提示词对象**：避免重复获取相同的提示词\n2. **批量编译**：对于大量相似请求，考虑批量处理\n3. **异步调用**：在需要时使用异步方式获取提示词\n\n### 安全考虑\n\n1. **敏感信息处理**：避免在提示词中硬编码敏感信息\n2. **访问控制**：确保只有授权用户可以修改提示词\n3. **审计日志**：记录提示词的访问和修改历史\n\n## 相关模块\n\n| 模块名称 | 功能说明 |\n|----------|----------|\n| RagaAICatalyst | 核心催化剂类，提供认证和基础服务 |\n| Tracer | 追踪模块，用于监控应用行为 |\n| Dataset | 数据集管理，与提示词配合使用 |\n| Evaluation | 评估模块，用于验证提示词效果 |\n| RedTeaming | 红队测试，评估提示词安全性 |\n\n## 常见问题\n\n### Q: 如何处理提示词版本冲突？\n\n**A:** 建议在获取提示词时明确指定版本号，避免因默认版本更新导致的行为差异。\n\n### Q: 提示词编译失败怎么办？\n\n**A:** 首先检查变量名称是否与模板定义一致，其次确认所有必填变量都已提供。\n\n### Q: 如何管理大量提示词？\n\n**A:** 建议按功能模块或应用场景对提示词进行分组，使用规范化的命名约定便于检索。\n\n## 总结\n\n提示词管理是 RagaAI Catalyst 平台的重要功能，通过提供统一的接口和完善的管理机制，帮助开发者更高效地管理和使用提示词模板。该模块支持版本控制、变量提取、动态编译等核心功能，可以广泛应用于问答系统、RAG 应用和 Agent 应用等多种场景。与平台的追踪、评估等模块配合使用，能够构建完整的 AI 应用开发工作流。\n\n---\n\n\n\n## 智能体追踪系统\n\n### 相关页面\n\n相关主题：[追踪器类型与框架支持](#tracer-types), [配置与认证](#configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/tracers/tracer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n- [ragaai_catalyst/tracers/agentic_tracing/__init__.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/__init__.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n- [docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n \n\n# 智能体追踪系统\n\n## 概述\n\n智能体追踪系统（Agentic Tracing System）是 RagaAI Catalyst 平台的核心组件之一，旨在为基于大语言模型的智能体应用提供全面的可观测性解决方案。该系统通过自动插桩和自定义追踪两种模式，捕获智能体执行过程中的关键信息，包括 LLM 调用、工具执行、代理行为、用户交互、文件操作和网络通信等各个环节。\n\n智能体追踪系统支持多种主流 AI 框架的深度集成，包括 LangGraph、LangChain、CrewAI、SmolaAgents、OpenAI Agents 和 LlamaIndex 等。系统将这些框架的执行轨迹统一标准化后上传至 RagaAI 云端平台，便于开发者进行性能分析、调试和优化。\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n## 架构设计\n\n### 整体架构\n\n智能体追踪系统采用分层架构设计，从底层到顶层依次包括数据采集层、标准化处理层和上传服务层。各层之间通过事件驱动的方式进行通信，确保追踪数据的完整性和时效性。\n\n```mermaid\ngraph TD\n A[应用层] --> B[自动插桩层]\n A --> C[手动追踪层]\n B --> D[事件收集器]\n C --> D\n D --> E[数据标准化处理器]\n E --> F[轨迹导出器]\n F --> G[RagaAI 云端平台]\n \n B -.-> H[LLM 插桩]\n B -.-> I[工具插桩]\n B -.-> J[代理插桩]\n B -.-> K[用户交互插桩]\n B -.-> L[文件IO插桩]\n B -.-> M[网络插桩]\n B -.-> N[自定义插桩]\n```\n\n### 核心组件\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| Tracer | 主入口类，负责初始化和配置追踪器 | ragaai_catalyst/tracers/tracer.py |\n| AgenticTracing | 核心追踪逻辑基类 | ragaai_catalyst/tracers/agentic_tracing/__init__.py |\n| AgenticTracer | 基于 OpenInference 的追踪实现 | ragaai_catalyst/tracers/agentic_tracing/tracers/base.py |\n| RAGATraceExporter | 轨迹数据导出器 | ragaai_catalyst/tracers/exporters/ragaai_trace_exporter.py |\n| SystemMonitor | 系统资源监控模块 | ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py |\n| LLMTracerMixin | LLM 调用追踪混入类 | ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:1-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 支持的追踪器类型\n\n智能体追踪系统通过 `tracer_type` 参数区分不同的追踪目标。系统支持两大类追踪模式：**智能体类追踪器**和**RAG 类追踪器**。\n\n### 智能体类追踪器\n\n| tracer_type 参数值 | 支持框架 | 依赖包 |\n|------------------|---------|--------|\n| `agentic/langgraph` | LangGraph | langgraph |\n| `agentic/langchain` | LangChain | langchain-community |\n| `agentic/crewai` | CrewAI | crewai |\n| `agentic/smolagents` | SmolaAgents | smolagents |\n| `agentic/openai_agents` | OpenAI Agents SDK | openai |\n| `agentic/llamaindex` | LlamaIndex | llamaindex |\n| `agentic/haystack` | Haystack | haystack-ai |\n\n资料来源：[ragaai_catalyst/tracer.py:60-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### RAG 类追踪器\n\n| tracer_type 参数值 | 支持框架 | 依赖包 |\n|------------------|---------|--------|\n| `rag/langchain` | LangChain RAG 应用 | langchain-community |\n\n### 通用智能体追踪器\n\n当 `tracer_type` 设置为 `agentic`（不含具体框架后缀）时，系统将启用通用智能体追踪模式，同时支持 VertexAI、Anthropic、LiteLLM、OpenAI 等多个 LLM 提供商的插桩。\n\n资料来源：[ragaai_catalyst/tracer.py:80-150](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 快速入门\n\n### 环境配置\n\n在使用智能体追踪系统之前，需要确保已完成以下配置：\n\n```bash\npip install ragaai-catalyst\n```\n\n并设置环境变量或在代码中初始化认证信息：\n\n```python\nimport os\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n资料来源：[examples/all_llm_provider/config.py:1-20](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n\n### 自动插桩模式\n\n自动插桩是智能体追踪系统最便捷的使用方式。只需初始化追踪器并调用 `init_tracing` 函数，系统即可自动捕获应用中的各类操作。\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化 RagaAI Catalyst\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\" # 根据实际框架选择\n)\n\n# 启用自动插桩\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n### 自定义追踪模式\n\n对于需要精确控制追踪范围和时机的场景，系统提供两种自定义追踪方式：\n\n#### 方式一：上下文管理器方式\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"agentic/langgraph\"\n)\n\nwith tracer():\n # 需要追踪的代码块\n result = your_agent.run(\"用户输入\")\n```\n\n#### 方式二：手动启停方式\n\n```python\ntracer.start()\n\n# 需要追踪的代码\nresult = your_agent.run(\"用户输入\")\n\ntracer.stop()\n\n# 验证数据上传状态\nprint(tracer.get_upload_status())\n```\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n## Tracer 类详解\n\n### 构造函数参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| project_name | str | 必需 | RagaAI 项目名称 |\n| dataset_name | str | 必需 | 数据集名称 |\n| trace_name | str | None | 自定义轨迹名称 |\n| tracer_type | str | None | 追踪器类型 |\n| pipeline | object | None | 管道对象 |\n| metadata | dict | None | 自定义元数据 |\n| description | str | None | 追踪描述 |\n| timeout | int | 120 | 上传超时时间（秒） |\n| update_llm_cost | bool | True | 是否更新 LLM 成本 |\n| auto_instrumentation | dict | 见下方 | 自动插桩配置 |\n| interval_time | int | 2 | 上传间隔时间（秒） |\n| max_upload_workers | int | 30 | 最大上传线程数 |\n| external_id | str | None | 外部标识符 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:30-70](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### 自动插桩配置\n\n`auto_instrumentation` 参数用于精细控制自动插桩的范围，默认配置如下：\n\n```python\nauto_instrumentation = {\n 'llm': True, # LLM 调用追踪\n 'tool': True, # 工具执行追踪\n 'agent': True, # 代理行为追踪\n 'user_interaction': True, # 用户交互追踪\n 'file_io': True, # 文件操作追踪\n 'network': True, # 网络请求追踪\n 'custom': True # 自定义事件追踪\n}\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:40-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### 模型成本配置\n\n系统支持设置自定义模型成本，用于追踪 LLM 调用费用：\n\n```python\ntracer.set_model_cost({\n \"model_name\": \"gpt-4\",\n \"input_cost_per_million_token\": 6,\n \"output_cost_per_million_token\": 2.40\n})\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:100-130](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 与各框架的集成\n\n### CrewAI 集成\n\nCrewAI 是多智能体协作框架，RagaAI Catalyst 提供原生的 CrewAI 追踪支持：\n\n```python\nfrom crewai import Agent, Task, Crew, Process\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化追踪\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 创建 CrewAI 应用\nbrainstormer = Agent(\n role=\"创意生成器\",\n goal=\"生成创意性想法\",\n backstory=\"你是一位富有想象力的思考者\"\n)\n\ncrew = Crew(\n agents=[brainstormer],\n tasks=[brainstorm_task],\n process=Process.sequential\n)\n\nresult = crew.kickoff()\n```\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n\n### SmolaAgents 集成\n\nSmolaAgents 是轻量级智能体框架，适用于简单到中等复杂度的任务：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/smolagents\",\n)\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n\n### 自定义代理集成\n\n对于自定义代理应用，系统提供通用的智能体追踪支持：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ndef initialize_tracing():\n catalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n )\n\n tracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\", # 通用智能体模式\n )\n\n init_tracing(catalyst=catalyst, tracer=tracer)\n return tracer\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n\n## 工作流程\n\n智能体追踪系统的工作流程可划分为以下四个阶段：\n\n```mermaid\ngraph LR\n A[初始化] --> B[配置追踪器]\n B --> C[自动插桩/手动追踪]\n C --> D[数据收集]\n D --> E[数据标准化]\n E --> F[上传至云端]\n F --> G[查看分析结果]\n```\n\n### 阶段一：初始化\n\n在应用启动时，首先创建 `RagaAICatalyst` 实例和 `Tracer` 实例，建立与 RagaAI 平台的连接。\n\n### 阶段二：配置追踪器\n\n根据实际使用的框架选择合适的 `tracer_type`，并通过 `init_tracing` 函数启用自动插桩功能。\n\n### 阶段三：执行追踪\n\n应用运行时，追踪器自动捕获各类操作事件。对于需要特定追踪范围的场景，可使用上下文管理器或手动启停方式。\n\n### 阶段四：数据上传\n\n追踪数据经过标准化处理后，通过后台任务异步上传至 RagaAI 云端平台。用户可通过 `get_upload_status()` 方法查看上传状态。\n\n## 系统资源监控\n\n智能体追踪系统集成了系统资源监控功能，用于记录追踪期间的系统环境信息：\n\n| 监控项 | 说明 |\n|-------|------|\n| CPU | 处理器型号、核心数、线程数 |\n| 内存 | 总内存、可用内存 |\n| 磁盘 | 总容量、可用空间 |\n| 网络 | 上传/下载速度 |\n| Python 环境 | Python 版本、已安装包列表 |\n\n资料来源：[ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py:20-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py)\n\n## 最佳实践\n\n### 选择合适的追踪模式\n\n| 场景 | 推荐模式 |\n|-----|---------|\n| 快速集成，追踪全部操作 | 自动插桩模式 |\n| 精确控制追踪范围 | 上下文管理器模式 |\n| 长时间运行的后台任务 | 手动启停模式 |\n\n### 性能考虑\n\n- 默认上传间隔为 2 秒，可通过 `interval_time` 参数调整\n- 最大上传线程数为 30，可通过 `max_upload_workers` 参数调整\n- 对于高频调用场景，建议适当增大 `interval_time` 以减少网络开销\n\n### 安全性建议\n\n- 妥善保管 `access_key` 和 `secret_key`，避免硬编码在代码中\n- 推荐使用环境变量或配置中心管理敏感信息\n- 定期轮换认证凭证\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 追踪数据未上传 | 网络连接问题 | 检查网络配置和 `base_url` |\n| 框架未被识别 | `tracer_type` 配置错误 | 确认使用正确的追踪器类型 |\n| 数据不完整 | 插桩范围限制 | 检查 `auto_instrumentation` 配置 |\n| 上传超时 | `timeout` 过小 | 增大 `timeout` 参数值 |\n\n### 调试模式\n\n启用调试模式以获取详细日志：\n\n```python\nimport os\nos.environ[\"DEBUG\"] = \"1\"\n```\n\n设置后，追踪器将输出详细的调试信息，便于定位问题。\n\n## 总结\n\n智能体追踪系统是 RagaAI Catalyst 平台的核心功能之一，通过统一的标准化的追踪机制，为开发者提供跨框架的可观测性解决方案。该系统支持灵活的自动插桩和自定义追踪两种模式，兼容多种主流 AI 框架，并提供完整的资源监控和数据分析能力。无论是快速原型开发还是生产环境监控，智能体追踪系统都能提供有力的技术支持。\n\n---\n\n\n\n## 追踪器类型与框架支持\n\n### 相关页面\n\n相关主题：[智能体追踪系统](#agentic-tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/tracers/tracer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 追踪器类型与框架支持\n\n## 概述\n\nRagaAI Catalyst 的追踪器（Tracer）系统为各种 AI 代理和 LLM 框架提供统一的追踪和监控能力。通过支持多种主流框架，开发者可以在不同的技术栈中实现一致的追踪体验。\n\n追踪器类型的核心作用是根据不同的框架自动配置相应的检测器（Instrumentors），并通过统一的接口管理追踪生命周期，包括启动、停止和上传追踪数据。\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:1-50]()\n\n## 支持的追踪器类型\n\n### 追踪器类型总览\n\nRagaAI Catalyst 支持以下追踪器类型：\n\n| 追踪器类型 | 框架 | 说明 |\n|-----------|------|------|\n| `agentic/langgraph` | LangGraph | 图结构代理框架追踪 |\n| `agentic/langchain` | LangChain | 通用 LangChain 追踪 |\n| `agentic/llamaindex` | LlamaIndex | LlamaIndex 代理追踪 |\n| `agentic/smolagents` | SmolAgents | 轻量级代理框架追踪 |\n| `agentic/openai_agents` | OpenAI Agents | OpenAI 官方代理 SDK |\n| `agentic/haystack` | Haystack | Haystack AI 框架追踪 |\n| `agentic/crewai` | CrewAI | 多代理协作框架追踪 |\n| `agentic/autogen` | AutoGen | 微软 AutoGen 多代理框架 |\n| `rag/langchain` | LangChain (RAG) | LangChain RAG 专用追踪 |\n| `langchain` | LangChain | 传统 LangChain 追踪 |\n| `llamaindex` | LlamaIndex | 传统 LlamaIndex 追踪 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:45-90]()\n\n## 框架支持架构\n\n### 架构层次\n\n```mermaid\ngraph TD\n A[Tracer 追踪器主类] --> B[AgenticTracing 基础类]\n B --> C[框架特定检测器]\n \n C --> D[LLM 检测器]\n C --> E[Tool 检测器]\n C --> F[Agent 检测器]\n C --> G[User Interaction 检测器]\n \n D --> D1[LiteLLMInstrumentor]\n D --> D2[OpenAIInstrumentor]\n D --> D3[AnthropicInstrumentor]\n D --> D4[GroqInstrumentor]\n D --> D5[VertexAIInstrumentor]\n \n E --> E1[Tool Callbacks]\n F --> F1[Agent Callbacks]\n G --> G1[User Interaction Callbacks]\n \n H[RAGATraceExporter] --> I[追踪数据上传]\n```\n\n### 追踪器初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Tracer as Tracer 类\n participant Setup as 框架设置\n participant Instrumentor as 检测器\n \n User->>Tracer: 初始化 Tracer(tracer_type)\n Tracer->>Tracer: 验证 tracer_type\n Tracer->>Setup: 调用框架特定设置\n Setup->>Instrumentor: 加载对应 Instrumentors\n Instrumentor-->>Setup: 返回检测器实例\n Setup-->>Tracer: 完成配置\n Tracer-->>User: 返回 Tracer 实例\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:60-120]()\n\n## 追踪器核心参数\n\n### Tracer 类初始化参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `project_name` | str | 必需 | 项目名称 |\n| `dataset_name` | str | 必需 | 数据集名称 |\n| `tracer_type` | str | None | 追踪器类型 |\n| `trace_name` | str | None | 追踪名称 |\n| `pipeline` | object | None | 管道对象 |\n| `metadata` | dict | None | 元数据 |\n| `description` | str | None | 描述信息 |\n| `timeout` | int | 120 | 超时时间（秒） |\n| `update_llm_cost` | bool | True | 是否更新模型成本 |\n| `auto_instrumentation` | dict | 见下文 | 自动检测配置 |\n| `interval_time` | int | 2 | 间隔时间（秒） |\n| `max_upload_workers` | int | 30 | 最大上传工作线程数 |\n| `external_id` | str | None | 外部 ID |\n\n### auto_instrumentation 配置\n\n`auto_instrumentation` 参数控制自动检测的组件类型：\n\n| 键 | 类型 | 默认值 | 说明 |\n|----|------|--------|------|\n| `llm` | bool | True | LLM 调用追踪 |\n| `tool` | bool | True | 工具调用追踪 |\n| `agent` | bool | True | 代理行为追踪 |\n| `user_interaction` | bool | True | 用户交互追踪 |\n| `file_io` | bool | True | 文件 IO 追踪 |\n| `network` | bool | True | 网络请求追踪 |\n| `custom` | bool | True | 自定义追踪 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:30-45]()\n\n## 框架集成示例\n\n### LangGraph 框架集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n\ntracer = Tracer(\n project_name=\"my-project\",\n dataset_name=\"my-dataset\",\n tracer_type=\"agentic/langgraph\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/langgraph/personal_research_assistant/research_assistant.py:20-35]()\n\n### CrewAI 框架集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:10-25]()\n\n### SmolAgents 框架集成\n\nSmolAgents 框架通过 `SmolagentsInstrumentor` 进行检测：\n\n```python\ntracer = Tracer(\n project_name=\"project_name\",\n dataset_name=\"dataset_name\",\n tracer_type=\"agentic/smolagents\"\n)\n```\n\n### 自定义代理集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\")\n)\n\ntracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\" # 通用代理追踪\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:10-25]()\n\n## LLM 检测器支持\n\nRagaAI Catalyst 支持多种 LLM 提供商的检测：\n\n| 提供商 | 检测器类 | 说明 |\n|--------|----------|------|\n| OpenAI | `OpenAIInstrumentor` | OpenAI GPT 系列 |\n| Anthropic | `AnthropicInstrumentor` | Claude 系列 |\n| Google VertexAI | `VertexAIInstrumentor` | Google Gemini 等 |\n| Groq | `GroqInstrumentor` | Groq LPU |\n| LiteLLM | `LiteLLMInstrumentor` | 统一 LLM 接口 |\n\n检测器自动根据 `tracer_type` 进行加载：\n\n```python\nif tracer_type in ['agentic/crewai']:\n from openinference.instrumentation.vertexai import VertexAIInstrumentor\n instrumentors.append((VertexAIInstrumentor, []))\n from openinference.instrumentation.anthropic import AnthropicInstrumentor\n instrumentors.append((AnthropicInstrumentor, []))\n from openinference.instrumentation.groq import GroqInstrumentor\n instrumentors.append((GroqInstrumentor, []))\n from openinference.instrumentation.litellm import LiteLLMInstrumentor\n instrumentors.append((LiteLLMInstrumentor, []))\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:65-85]()\n\n## 追踪生命周期管理\n\n### 追踪启动和停止\n\nRagaAI Catalyst 提供两种追踪控制方式：\n\n#### 方式一：上下文管理器\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\nwith tracer():\n # 您的代码逻辑\n pass\n```\n\n#### 方式二：手动控制\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\ntracer.start()\n# 您的代码逻辑\ntracer.stop()\n\n# 验证上传状态\nprint(tracer.get_upload_status())\n```\n\n资料来源：[quickstart.md](quickstart.md)\n\n### 不同框架的启动行为\n\n| 追踪器类型 | 启动方式 | 特殊处理 |\n|-----------|----------|----------|\n| `langchain` | `super().start()` | 直接调用父类 |\n| `llamaindex` | `LlamaIndexInstrumentationTracer` | 自定义转换器 |\n| `rag/langchain` | `super().start()` | RAG 专用处理 |\n| 其他 agentic 类型 | `super().start()` | 统一处理 |\n\n```python\ndef start(self):\n if self.tracer_type == \"langchain\":\n super().start()\n return self\n elif self.tracer_type == \"llamaindex\":\n self.llamaindex_tracer = LlamaIndexInstrumentationTracer(self._pass_user_data())\n return self.llamaindex_tracer.start()\n else:\n super().start()\n return self\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:180-195]()\n\n## 自动检测与手动检测\n\n### 自动检测（Auto-Instrumentation）\n\n自动检测在初始化时启用，可通过 `init_tracing` 函数配置：\n\n```python\nfrom ragaai_catalyst import init_tracing, Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### 自动检测组件控制\n\n可通过 `auto_instrumentation` 参数精细控制：\n\n```python\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\",\n auto_instrumentation={\n 'llm': True, # 启用 LLM 追踪\n 'tool': True, # 启用工具追踪\n 'agent': True, # 启用代理追踪\n 'user_interaction': True, # 启用用户交互追踪\n 'file_io': True, # 启用文件 IO 追踪\n 'network': True, # 启用网络请求追踪\n 'custom': True # 启用自定义追踪\n }\n)\n```\n\n### 框架特定检测器\n\n| 框架 | 检测器类 | 导入路径 |\n|------|----------|----------|\n| LangGraph | `LangGraphInstrumentor` | `openinference.instrumentation.langgraph` |\n| LangChain | `LangChainInstrumentor` | `openinference.instrumentation.langchain` |\n| SmolAgents | `SmolagentsInstrumentor` | `openinference.instrumentation.smolagents` |\n| OpenAI Agents | `OpenAIAgentsInstrumentor` | `openinference.instrumentation.openai_agents` |\n| AutoGen | `AutogenInstrumentor` | `openinference.instrumentation.autogen` |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:90-115]()\n\n## 模型成本追踪\n\n### 设置自定义模型成本\n\nRagaAI Catalyst 支持追踪 LLM 调用成本：\n\n```python\ntracer.set_model_cost({\n \"model_name\": \"gpt-4\",\n \"input_cost_per_million_token\": 6,\n \"output_cost_per_million_token\": 2.40\n})\n```\n\n### 成本追踪参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model_name` | str | 模型名称 |\n| `input_cost_per_million_token` | float | 每百万输入 token 成本 |\n| `output_cost_per_million_token` | float | 每百万输出 token 成本 |\n\n可通过 `update_llm_cost=False` 禁用成本更新：\n\n```python\ntracer = Tracer(\n project_name=\"project\",\n dataset_name=\"dataset\",\n tracer_type=\"agentic/langgraph\",\n update_llm_cost=False\n)\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:125-145]()\n\n## 快速参考\n\n### 追踪器类型选择指南\n\n| 应用场景 | 推荐追踪器类型 |\n|----------|----------------|\n| LangGraph 工作流 | `agentic/langgraph` |\n| LangChain 链式调用 | `agentic/langchain` 或 `langchain` |\n| LlamaIndex 查询引擎 | `agentic/llamaindex` |\n| SmolAgents 代理 | `agentic/smolagents` |\n| CrewAI 多代理系统 | `agentic/crewai` |\n| RAG 应用（LangChain） | `rag/langchain` |\n| 通用代理应用 | `Agentic` 或 `agentic` |\n| AutoGen 多代理 | `agentic/autogen` |\n\n### 最小配置示例\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing, Tracer\n\n# 初始化 Catalyst\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\"\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=\"my-project\",\n dataset_name=\"my-dataset\",\n tracer_type=\"agentic/langgraph\"\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 使用上下文管理器运行代码\nwith tracer():\n # 您的代理代码\n pass\n```\n\n资料来源：[README.md](README.md)\n\n## 错误处理与调试\n\n### 常见问题处理\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 追踪器未启动 | 未调用 `init_tracing` | 确保在代码前调用 `init_tracing` |\n| 框架未检测到 | tracer_type 不匹配 | 检查框架对应的正确 tracer_type |\n| 上传失败 | 网络或认证问题 | 检查 `get_upload_status()` 返回状态 |\n| LlamaIndex 追踪失败 | 未先调用 `start()` | 确保显式调用 `tracer.start()` |\n\n### 调试模式\n\n启用调试模式查看详细日志：\n\n```bash\nexport DEBUG=1\n```\n\n或在代码中设置日志级别：\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:15-20]()\n\n---\n\n\n\n## 合成数据生成\n\n### 相关页面\n\n相关主题：[提示词管理](#prompt-management), [数据集管理](#dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n \n\n# 合成数据生成\n\n## 概述\n\n合成数据生成（Synthetic Data Generation）是 RagaAI Catalyst 平台提供的重要功能模块之一。该模块允许用户通过 LLM（大型语言模型）自动生成测试数据集，用于 RAG 应用的质量评估和测试场景构建。\n\n在 RAG（检索增强生成）应用开发过程中，高质量测试数据的获取往往是开发者面临的主要挑战之一。合成数据生成功能通过利用强大的语言模型能力，帮助开发者快速创建多样化的测试用例，从而提升应用的质量和鲁棒性。\n\n## 核心功能特性\n\nRagaAI Catalyst 的合成数据生成模块具有以下核心能力：\n\n| 功能特性 | 描述 |\n|---------|------|\n| 多源数据生成 | 支持基于不同数据源生成合成数据 |\n| Schema 映射 | 提供灵活的数据 Schema 映射机制 |\n| 批量生成 | 支持批量生成测试数据集 |\n| 质量控制 | 内置数据质量验证机制 |\n| 格式支持 | 支持 CSV、JSONL 等多种输出格式 |\n\n## 系统架构\n\n合成数据生成模块在 RagaAI Catalyst 整体架构中扮演着数据准备的关键角色。以下是平台的核心架构图：\n\n```mermaid\ngraph TD\n A[RagaAI Catalyst] --> B[项目管理]\n A --> C[数据集管理]\n A --> D[评估框架]\n A --> E[跟踪系统]\n A --> F[提示词管理]\n A --> G[Guardrail 管理]\n A --> H[红队测试]\n A --> I[合成数据生成]\n \n I --> I1[数据源配置]\n I --> I2[Schema 映射]\n I --> I3[生成引擎]\n I --> I4[质量验证]\n \n C --> C1[CSV 导入]\n C --> C2[DataFrame 导入]\n C --> C3[JSONL 导入]\n```\n\n## 工作流程\n\n合成数据生成的标准工作流程包含以下步骤：\n\n```mermaid\ngraph TD\n A[初始化 RagaAICatalyst] --> B[配置数据集管理器]\n B --> C[定义 Schema 映射]\n C --> D[调用合成数据生成接口]\n D --> E[执行 LLM 生成]\n E --> F[质量验证]\n F --> G{验证通过?}\n G -->|是| H[保存生成的数据]\n G -->|否| I[重新生成或调整参数]\n I --> D\n H --> J[集成到评估流程]\n```\n\n## 使用方法\n\n### 初始化配置\n\n使用合成数据生成功能前，需要完成基础配置：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n```\n\n### 数据集管理集成\n\n合成数据生成与数据集管理模块紧密集成，支持将生成的数据直接导入到项目数据集中：\n\n```python\nfrom ragaai_catalyst import Dataset\n\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"SyntheticDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n```\n\n## 与评估框架的集成\n\n合成数据生成的主要用途之一是为评估框架提供测试数据。评估框架支持多种内置指标：\n\n```python\nfrom ragaai_catalyst import Evaluation\n\nevaluation = Evaluation(\n project_name=\"Project_Name\",\n dataset_name=\"SyntheticDataset\"\n)\n\n# 添加评估指标\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\", \"threshold\": {\"gte\": 0.5}},\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n## 支持的 LLM 提供商\n\n合成数据生成功能支持多种 LLM 提供商，包括：\n\n| 提供商 | 支持状态 | 说明 |\n|-------|---------|------|\n| OpenAI | ✅ 完全支持 | 支持 GPT-4o、GPT-4o-mini 等模型 |\n| Anthropic | ✅ 完全支持 | 支持 Claude 系列模型 |\n| Google Generative AI | ✅ 完全支持 | 支持 Gemini 系列模型 |\n| xAI | ✅ 完全支持 | 支持 Grok 系列模型 |\n| Vertex AI | ✅ 完全支持 | 支持 Google Cloud Vertex AI |\n| Ollama | ✅ 完全支持 | 支持本地部署的模型 |\n\n支持的追踪器类型包括：`agentic/langgraph`、`agentic/langchain`、`agentic/smolagents`、`agentic/openai_agents`、`agentic/llamaindex`、`agentic/haystack` 等。\n\n## 最佳实践\n\n### 1. Schema 设计建议\n\n在设计合成数据的 Schema 时，应注意以下要点：\n\n- 确保字段命名清晰且具有描述性\n- 定义明确的字段类型和数据约束\n- 合理规划必填字段和可选字段\n\n### 2. 数据质量控制\n\n建议在生成合成数据后进行以下质量检查：\n\n- 验证数据的完整性和一致性\n- 检查数据分布的合理性\n- 确保生成的问答对具有逻辑性\n\n### 3. 与真实数据结合\n\n最佳实践建议将合成数据与真实数据结合使用：\n\n- 使用合成数据补充边缘案例\n- 使用真实数据验证合成数据的质量\n- 定期更新合成数据以覆盖新场景\n\n## 相关模块\n\n合成数据生成与其他 RagaAI Catalyst 模块协同工作：\n\n- **数据集管理**：存储和管理生成的合成数据\n- **评估框架**：使用合成数据进行模型评估\n- **提示词管理**：优化数据生成的提示词模板\n- **跟踪系统**：监控数据生成过程的性能\n\n## 总结\n\n合成数据生成是 RagaAI Catalyst 平台中用于自动化测试数据创建的核心功能。通过与多种 LLM 提供商的集成，开发者可以灵活地生成高质量的测试数据集，有效提升 RAG 应用的开发和评估效率。该功能与平台的数据集管理、评估框架等模块紧密集成，为用户提供了一整套完整的数据准备和评估解决方案。\n\n---\n\n\n\n## 安全护栏管理\n\n### 相关页面\n\n相关主题：[评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/guardrails_manager.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/guardrails_manager.py)\n- [ragaai_catalyst/guard_executor.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/guard_executor.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n \n\n# 安全护栏管理\n\n## 概述\n\n安全护栏管理（Guardrail Management）是RagaAI Catalyst平台的核心功能模块之一，旨在为AI应用提供实时的输入输出安全检查与过滤机制。该模块通过预定义的检测器和自定义规则，对LLM（大型语言模型）的输入提示词和生成内容进行多维度安全评估，确保AI应用在预设的安全边界内运行。\n\n安全护栏管理的主要职责包括：\n\n- **输入护栏**：在用户输入到达LLM之前进行内容审查和过滤\n- **输出护栏**：对模型生成的回答进行安全合规性检查\n- **策略配置**：支持用户自定义检测规则和响应策略\n- **结果追踪**：记录每次安全检查的执行结果和决策依据\n\n资料来源：[README.md:1-15]()\n\n## 核心组件架构\n\nRagaAI Catalyst的安全护栏系统由两个核心模块组成，它们协同工作以提供完整的安全保护能力。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Guardrails Manager]\n B --> C{检测器选择}\n C --> D[内置检测器]\n C --> E[自定义检测器]\n D --> F[Guard Executor]\n E --> F\n F --> G[安全决策]\n G --> H{通过?}\n H -->|是| I[转发至LLM]\n H -->|否| J[拦截/过滤]\n I --> K[LLM响应]\n K --> L[输出护栏检查]\n L --> M{合规?}\n M -->|是| N[返回用户]\n M -->|否| O[内容过滤]\n J --> P[返回安全响应]\n O --> P\n N --> P\n```\n\n### Guardrails Manager\n\n`GuardrailsManager`是护栏系统的主入口模块，负责护栏实例的创建、配置和管理。该模块提供了统一的API接口，使开发者能够便捷地集成安全护栏功能到现有应用中。\n\n主要功能特性：\n\n- **实例生命周期管理**：创建、配置、激活和停用护栏实例\n- **检测器注册**：支持注册内置检测器和自定义检测器\n- **规则链配置**：定义多个检测器的执行顺序和组合逻辑\n- **运行时配置**：支持热更新检测规则而无需重启应用\n\n### Guard Executor\n\n`GuardExecutor`是护栏系统的执行引擎，负责实际运行安全检查逻辑并返回决策结果。该模块封装了底层的检测算法和策略评估逻辑。\n\n核心职责：\n\n- **检测执行**：调用已注册的检测器对输入/输出进行评估\n- **策略评估**：根据配置的策略规则做出最终决策\n- **结果聚合**：合并多个检测器的结果生成统一报告\n- **异常处理**：处理检测过程中的异常情况并提供降级策略\n\n资料来源：[guardrails_manager.py:1-50]()\n\n## 核心数据结构\n\n安全护栏系统使用以下关键数据结构来描述检测规则和执行结果。\n\n### 检测器定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `name` | string | 是 | 检测器唯一标识名称 |\n| `type` | string | 是 | 检测器类型：`builtin`（内置）或 `custom`（自定义） |\n| `description` | string | 否 | 检测器的功能描述 |\n| `config` | dict | 否 | 检测器的配置参数 |\n| `threshold` | float | 否 | 检测阈值，范围0.0-1.0 |\n| `action` | string | 否 | 触发后的动作：`block`、`warn`、`log` |\n\n### 护栏执行结果\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| `passed` | boolean | 是否通过安全检查 |\n| `detections` | list | 检测到的违规项列表 |\n| `scores` | dict | 各检测器的置信度评分 |\n| `action_taken` | string | 实际执行的动作 |\n| `timestamp` | datetime | 执行时间戳 |\n\n资料来源：[guard_executor.py:1-80]()\n\n## 初始化与配置\n\n在使用安全护栏功能之前，需要正确初始化相关的配置。\n\n### 基础配置\n\n安全护栏模块通过RagaAI Catalyst的统一认证体系进行身份验证。开发者需要在环境变量中配置以下凭证：\n\n| 环境变量 | 说明 |\n|----------|------|\n| `RAGAAI_CATALYST_ACCESS_KEY` | RagaAI Catalyst访问密钥 |\n| `RAGAAI_CATALYST_SECRET_KEY` | RagaAI Catalyst秘钥 |\n| `RAGAAI_CATALYST_BASE_URL` | API服务基础URL |\n\n初始化代码示例：\n\n```python\nimport os\nfrom ragaai_catalyst import RagaAICatalyst\n\n# 初始化RagaAI Catalyst客户端\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:1-20]()\n\n### 护栏管理器初始化\n\n创建护栏管理器实例并配置检测器：\n\n```python\nfrom ragaai_catalyst import GuardrailsManager\n\n# 创建护栏管理器\nguardrails = GuardrailsManager(\n project_name=\"my_secure_app\",\n dataset_name=\"guardrails_config\",\n detector_config=[\n {\n \"name\": \"harmful_content\",\n \"type\": \"builtin\",\n \"threshold\": 0.7,\n \"action\": \"block\"\n },\n {\n \"name\": \"personal_info\",\n \"type\": \"custom\",\n \"description\": \"检测个人信息泄露\",\n \"threshold\": 0.5,\n \"action\": \"warn\"\n }\n ]\n)\n```\n\n## 内置检测器\n\nRagaAI Catalyst提供了多种内置检测器，覆盖常见的安全风险场景。\n\n### 可用内置检测器\n\n| 检测器名称 | 检测内容 | 默认阈值 |\n|------------|----------|----------|\n| `harmful_content` | 有害内容（暴力、仇恨、自残等） | 0.6 |\n| `stereotypes` | 刻板印象和歧视性内容 | 0.5 |\n| `personal_info` | 个人隐私信息泄露 | 0.7 |\n| `prompt_injection` | 提示词注入攻击 | 0.8 |\n| `toxic_language` | 有毒语言和辱骂性内容 | 0.6 |\n| `misinformation` | 虚假信息和误导性内容 | 0.5 |\n\n### 自定义检测器\n\n除了内置检测器外，开发者可以创建自定义检测器来满足特定业务需求：\n\n```python\n# 定义自定义检测器配置\ncustom_detector = {\n \"name\": \"prevent_sensitive_topics\",\n \"type\": \"custom\",\n \"description\": \"防止讨论敏感话题\",\n \"config\": {\n \"blocked_topics\": [\"politics\", \"religion\", \"conspiracy\"],\n \"match_mode\": \"any\" # 或 \"all\"\n },\n \"threshold\": 0.5,\n \"action\": \"block\"\n}\n```\n\n## 执行流程\n\n安全护栏的执行遵循标准的处理流程，确保每个请求都经过适当的安全检查。\n\n```mermaid\ngraph TD\n A[接收输入请求] --> B[参数验证]\n B --> C{参数有效?}\n C -->|否| D[返回验证错误]\n C -->|是| E[加载检测器配置]\n E --> F[执行输入护栏]\n F --> G[遍历检测器列表]\n G --> H{当前检测器}\n H -->|内置| I[调用内置检测逻辑]\n H -->|自定义| J[调用自定义检测逻辑]\n I --> K[计算风险评分]\n J --> K\n K --> L{评分>=阈值?}\n L -->|是| M[记录违规项]\n L -->|否| N[继续下一检测器]\n M --> O[触发对应动作]\n O --> N\n N --> P{还有检测器?}\n P -->|是| G\n P -->|否| Q[汇总检查结果]\n Q --> R{全部通过?}\n R -->|是| S[转发至LLM处理]\n R -->|否| T[执行拦截/过滤]\n S --> U[获取LLM响应]\n U --> V[执行输出护栏]\n V --> W[返回最终响应]\n T --> W\n```\n\n## 集成使用模式\n\n安全护栏系统支持多种集成方式，以适应不同的应用架构场景。\n\n### 模式一：独立护栏服务\n\n在独立的微服务架构中部署护栏功能：\n\n```python\nfrom ragaai_catalyst import GuardrailsManager, GuardExecutor\n\n# 创建护栏管理器和执行器\nguardrails_manager = GuardrailsManager(\n project_name=\"guardrail_service\",\n detector_config=[...]\n)\n\nguard_executor = GuardExecutor(\n detectors=guardrails_manager.get_detectors()\n)\n\ndef process_request(user_input):\n # 执行输入检查\n result = guard_executor.execute(\n content=user_input,\n direction=\"input\"\n )\n \n if not result.passed:\n return {\"error\": \"内容不符合安全要求\", \"details\": result.detections}\n \n # 继续处理流程\n return llm.process(user_input)\n```\n\n### 模式二：中间件集成\n\n将护栏功能作为中间件集成到现有应用框架中：\n\n```python\nfrom ragaai_catalyst import GuardrailsMiddleware\n\n# 创建护栏中间件\nguardrails_middleware = GuardrailsMiddleware(\n detector_config=[...],\n middleware_config={\n \"log_all_requests\": True,\n \"fail_open\": False # 安全失败模式\n }\n)\n\n# 应用中间件\napp.add_middleware(guardrails_middleware)\n```\n\n资料来源：[quickstart.md:50-100]()\n\n## 最佳实践\n\n### 配置优化建议\n\n1. **分层检测策略**：根据风险等级配置不同的检测器和阈值\n2. **性能权衡**：避免配置过多的高开销检测器\n3. **持续迭代**：定期审查检测结果，优化检测规则\n\n### 安全加固建议\n\n| 场景 | 推荐配置 |\n|------|----------|\n| 用户输入验证 | 启用所有内置检测器，阈值0.6 |\n| 高风险应用 | 添加自定义检测器，启用strict模式 |\n| 低延迟需求 | 减少自定义检测器，预设缓存策略 |\n| 合规要求严格 | 启用完整审计日志，配置双重验证 |\n\n## 错误处理与降级\n\n护栏系统实现了完善的错误处理机制，确保在异常情况下应用仍能正常运行。\n\n### 异常类型\n\n| 异常类型 | 触发条件 | 默认处理 |\n|----------|----------|----------|\n| `DetectorNotFoundError` | 检测器配置错误 | 返回配置错误 |\n| `ExecutionTimeoutError` | 检测超时 | 降级放行并记录 |\n| `ConfigurationError` | 初始化配置错误 | 阻止启动 |\n| `QuotaExceededError` | API配额超限 | 限流处理 |\n\n### 降级策略配置\n\n```python\nguardrails = GuardrailsManager(\n project_name=\"my_app\",\n detector_config=[...],\n fallback_config={\n \"on_detection_error\": \"allow\", # 检测异常时默认放行\n \"on_timeout\": \"allow\", # 超时时默认放行\n \"on_quota_exceeded\": \"block\", # 配额超限默认拦截\n \"log_fallbacks\": True # 记录降级事件\n }\n)\n```\n\n## 相关功能模块\n\n安全护栏管理与RagaAI Catalyst的其他核心功能紧密集成。\n\n```mermaid\ngraph LR\n A[安全护栏管理] --> B[项目管理]\n A --> C[数据集管理]\n A --> D[追踪系统]\n A --> E[评估框架]\n B --> F[统一认证]\n C --> F\n D --> F\n E --> F\n```\n\n- **项目管理**：护栏配置作为项目元数据进行管理\n- **数据集管理**：安全测试数据集用于验证护栏效果\n- **追踪系统**：记录护栏执行事件用于审计分析\n- **评估框架**：评估护栏的检出率和误报率\n\n资料来源：[README.md:1-50]()\n\n## 总结\n\nRagaAI Catalyst的安全护栏管理模块提供了一套完整、可扩展的安全保护解决方案。通过内置检测器与自定义检测器的组合，以及灵活的策略配置机制，开发者能够快速为AI应用构建坚实的安全防线。该模块与RagaAI Catalyst平台的认证系统、项目管理和追踪功能深度集成，为企业级AI应用提供了全方位的安全保障能力。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：raga-ai-hub/RagaAI-Catalyst\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：2.1.7.1。\n\n## 1. 安装坑 · 来源证据：2.1.7.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass.\n\n## 5. 运行坑 · 来源证据：2.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：2.2.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：2.2.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v2.1.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：2.1.6.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daf5807f609141008dc6aaadbc15d774 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：2.1.6.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0790ea07d026457a8eb6bf9e454fdcfa | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：2.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.2.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f1b8373166c14c4dba527f91193c93f1 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Authorization receipts for agent traces — signed governance proof per traced action\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Authorization receipts for agent traces — signed governance proof per traced action\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f70b1d74d8064a45bd97566d464f6f0e | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_534211e56e854a00af1a687847a67d77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | release_recency=unknown\n\n\n",
"markdown_key": "ragaai-catalyst",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:847717439",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst"
},
{
"evidence_id": "art_c346c6b8018a434c8f4408f8f6ef6e2f",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/raga-ai-hub/RagaAI-Catalyst#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "RagaAI-Catalyst 说明书",
"toc": [
"https://github.com/raga-ai-hub/RagaAI-Catalyst 项目说明书",
"目录",
"安装与快速开始",
"概述",
"安装前置条件",
"安装方式",
"认证配置",
"快速开始工作流",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "ab67893310891140211280a496402003e52cdab5",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"requirements.txt",
"docs/trace_management.md",
"docs/dataset_management.md",
"docs/agentic_tracing.md",
"docs/prompt_management.md",
"examples/all_llm_provider/all_llm_provider.py",
"examples/all_llm_provider/run_all_llm_provider.py",
"examples/all_llm_provider/config.py",
"examples/haystack/news_fetching/news_fetching.py",
"examples/haystack/news_fetching/README.md",
"examples/llamaindex_examples/legal_research_rag/legal_rag.py",
"examples/pii_masking_example/llamaindex_agentic_fastapi/app_presidio.py",
"examples/pii_masking_example/llamaindex_agentic_fastapi/request.py",
"examples/pii_masking_example/llamaindex_agentic_fastapi/app.py",
"examples/smolagents/most_upvoted_paper/README.md",
"examples/smolagents/most_upvoted_paper/most_upvoted_paper.py",
"examples/openai_agents_sdk/youtube_summary_agent/youtube_summary_agent.py",
"examples/openai_agents_sdk/youtube_summary_agent/README.md",
"examples/openai_agents_sdk/email_data_extraction_agent/data_extraction_email.py",
"examples/openai_agents_sdk/email_data_extraction_agent/README.md",
"examples/custom_agents/travel_agent/agents.py",
"examples/custom_agents/travel_agent/tools.py",
"examples/custom_agents/travel_agent/main.py",
"examples/custom_agents/travel_agent/config.py",
"examples/crewai/scifi_writer/scifi_writer.py",
"examples/crewai/scifi_writer/README.md",
"examples/langgraph/personal_research_assistant/README.md",
"examples/langgraph/personal_research_assistant/research_assistant.py",
"examples/langchain/medical_rag/diagnosis_agent.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# ragaai-catalyst - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 ragaai-catalyst 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install ragaai-catalyst` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：研究结论、引用和实验结果不能在安装前相信。\n- **继续会触碰**：研究判断、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。\n- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`Quickstart.md`, `README.md`, `quickstart.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：189\n- 重要文件覆盖：40/189\n- 证据索引条目：41\n- 角色 / Skill 条目：19\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 ragaai-catalyst 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 ragaai-catalyst 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 ragaai-catalyst 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 19 个角色 / Skill / 项目文档条目。\n\n- **RagaAI Catalyst ! GitHub release latest by date https://img.shields.io/github/v/release/raga-ai-hub/ragaai-cataly…**（project_doc）：RagaAI Catalyst ! GitHub release latest by date https://img.shields.io/github/v/release/raga-ai-hub/ragaai-catalyst ! GitHub stars https://img.shields.io/github/stars/raga-ai-hub/ragaai-catalyst?style=social ! Issues https://img.shields.io/github/issues/raga-ai-hub/ragaai-catalyst 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **RagaAI Catalyst Test Suite**（project_doc）：Description This test suite validates the functionality of RagaAI Catalyst using pytest. It includes: - Unit tests for core components - Integration tests for key workflows - Tests different LLM provider - Automated test reporting capabilities 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/crewai/scifi_writer/README.md`\n- **Haystack News Fetching Example with RagaAI Catalyst**（project_doc）：Haystack News Fetching Example with RagaAI Catalyst 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/haystack/news_fetching/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/langgraph/personal_research_assistant/README.md`\n- **Email Data Extraction with OpenAI Agents SDK**（project_doc）：Email Data Extraction with OpenAI Agents SDK 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/openai_agents_sdk/email_data_extraction_agent/README.md`\n- **YouTube Summary Agent with OpenAI Agents SDK**（project_doc）：YouTube Summary Agent with OpenAI Agents SDK 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/openai_agents_sdk/youtube_summary_agent/README.md`\n- **Most Upvoted Paper Summarizer**（project_doc）：This script fetches, downloads, and summarizes the most upvoted paper from Hugging Face daily papers. It uses SmoLAgents to create a pipeline that: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/smolagents/most_upvoted_paper/README.md`\n- **Agentic Tracing**（project_doc）：This module provides tracing functionality for agentic AI systems, helping track and analyze various aspects of AI agent behavior including LLM interactions, tool usage, and network activities. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ragaai_catalyst/tracers/agentic_tracing/README.md`\n- **Agentic Tracing**（project_doc）：Agentic Tracing The module includes utilities for cost tracking, performance monitoring, and debugging agent behavior. This helps in understanding and optimizing AI agent performance while maintaining transparency in agent operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agentic_tracing.md`\n- **Dataset Management**（project_doc）：Create and manage datasets easily for your projects using the ragaai catalyst library. This guide provides steps to list, create, and manage datasets efficiently. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/dataset_management.md`\n- **Prompt Management**（project_doc）：The Prompt Management feature in RagaAI Catalyst allows you to efficiently manage, retrieve, and use prompts in your projects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/prompt_management.md`\n- **Trace Management**（project_doc）：Record and analyse trace using the ragaai catalyst library. This guide provides steps to initialize tracer with project and dataset name langchain and llama-index ,run tracer and add context,stop the tracer,list dataset,add rows and column and evalutaion on tracer datasets efficiently. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/trace_management.md`\n- **Pull Request Template**（project_doc）：Description Provide a brief description of the changes in this PR 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Quickstart RagaAI Catalyst**（project_doc）：To install the RagaAI Catalyst package, run the following command in your terminal: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`Quickstart.md`\n- **Quickstart**（project_doc）：To install the RagaAI Catalyst package, run the following command in your terminal: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`quickstart.md`\n- **Bug report**（project_doc）：Describe the Bug A clear and concise description of the problem. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature request**（project_doc）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Legacy of Terra Nova**（project_doc）：In the year 2147, Terra Nova stood as a beacon of progress, elegantly juxtaposed against the dusty ruins of an ancient civilization long forgotten. Towering structures pierced the sky, their surfaces shimmering with a blend of advanced technology and holographic advertisements. Yet, beneath this glamorous exterior lay the remnants of an age past, a story begging to be unraveled. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/examples/crewai/scifi_writer/sci_fi_story.md`\n\n## 证据索引\n\n- 共索引 41 条证据。\n\n- **RagaAI Catalyst ! GitHub release latest by date https://img.shields.io/github/v/release/raga-ai-hub/ragaai-cataly…**（documentation）：RagaAI Catalyst ! GitHub release latest by date https://img.shields.io/github/v/release/raga-ai-hub/ragaai-catalyst ! GitHub stars https://img.shields.io/github/stars/raga-ai-hub/ragaai-catalyst?style=social ! Issues https://img.shields.io/github/issues/raga-ai-hub/ragaai-catalyst 证据：`README.md`\n- **RagaAI Catalyst Test Suite**（documentation）：Description This test suite validates the functionality of RagaAI Catalyst using pytest. It includes: - Unit tests for core components - Integration tests for key workflows - Tests different LLM provider - Automated test reporting capabilities 证据：`tests/README.md`\n- **Haystack News Fetching Example with RagaAI Catalyst**（documentation）：Haystack News Fetching Example with RagaAI Catalyst 证据：`examples/haystack/news_fetching/README.md`\n- **Email Data Extraction with OpenAI Agents SDK**（documentation）：Email Data Extraction with OpenAI Agents SDK 证据：`examples/openai_agents_sdk/email_data_extraction_agent/README.md`\n- **YouTube Summary Agent with OpenAI Agents SDK**（documentation）：YouTube Summary Agent with OpenAI Agents SDK 证据：`examples/openai_agents_sdk/youtube_summary_agent/README.md`\n- **Most Upvoted Paper Summarizer**（documentation）：This script fetches, downloads, and summarizes the most upvoted paper from Hugging Face daily papers. It uses SmoLAgents to create a pipeline that: 证据：`examples/smolagents/most_upvoted_paper/README.md`\n- **Agentic Tracing**（documentation）：This module provides tracing functionality for agentic AI systems, helping track and analyze various aspects of AI agent behavior including LLM interactions, tool usage, and network activities. 证据：`ragaai_catalyst/tracers/agentic_tracing/README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Agentic Tracing**（documentation）：Agentic Tracing The module includes utilities for cost tracking, performance monitoring, and debugging agent behavior. This helps in understanding and optimizing AI agent performance while maintaining transparency in agent operations. 证据：`docs/agentic_tracing.md`\n- **Dataset Management**（documentation）：Create and manage datasets easily for your projects using the ragaai catalyst library. This guide provides steps to list, create, and manage datasets efficiently. 证据：`docs/dataset_management.md`\n- **Prompt Management**（documentation）：The Prompt Management feature in RagaAI Catalyst allows you to efficiently manage, retrieve, and use prompts in your projects. 证据：`docs/prompt_management.md`\n- **Trace Management**（documentation）：Record and analyse trace using the ragaai catalyst library. This guide provides steps to initialize tracer with project and dataset name langchain and llama-index ,run tracer and add context,stop the tracer,list dataset,add rows and column and evalutaion on tracer datasets efficiently. 证据：`docs/trace_management.md`\n- **Pull Request Template**（documentation）：Description Provide a brief description of the changes in this PR 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Quickstart RagaAI Catalyst**（documentation）：To install the RagaAI Catalyst package, run the following command in your terminal: 证据：`Quickstart.md`\n- **Quickstart**（documentation）：To install the RagaAI Catalyst package, run the following command in your terminal: 证据：`quickstart.md`\n- **Bug Report**（documentation）：Describe the Bug A clear and concise description of the problem. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Request**（documentation）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Legacy of Terra Nova**（documentation）：In the year 2147, Terra Nova stood as a beacon of progress, elegantly juxtaposed against the dusty ruins of an ancient civilization long forgotten. Towering structures pierced the sky, their surfaces shimmering with a blend of advanced technology and holographic advertisements. Yet, beneath this glamorous exterior lay the remnants of an age past, a story begging to be unraveled. 证据：`tests/examples/crewai/scifi_writer/sci_fi_story.md`\n- **Model Costs**（structured_config）：{ \"sample spec\": { \"max tokens\": \"LEGACY parameter. set to max output tokens if provider specifies it. IF not set to max input tokens, if provider specifies it.\", \"max input tokens\": \"max input tokens, if the provider specifies it. if not default to max tokens\", \"max output tokens\": \"max output tokens, if the provider specifies it. if not default to max tokens\", \"input cost per token\": 0.0, \"output cost per token\": 0.0, \"litellm provider\": \"one of https://docs.litellm.ai/docs/providers\", \"mode\": \"one of chat, embedding, completion, image generation, audio transcription, audio speech\", \"supports function calling\": true, \"supports parallel function calling\": true, \"supports vision\": true, \"su… 证据：`ragaai_catalyst/tracers/agentic_tracing/utils/model_costs.json`\n- **Model Prices And Context Window Backup**（structured_config）：{ \"sample spec\": { \"max tokens\": \"LEGACY parameter. set to max output tokens if provider specifies it. IF not set to max input tokens, if provider specifies it.\", \"max input tokens\": \"max input tokens, if the provider specifies it. if not default to max tokens\", \"max output tokens\": \"max output tokens, if the provider specifies it. if not default to max tokens\", \"input cost per token\": 0.0000, \"output cost per token\": 0.000, \"litellm provider\": \"one of https://docs.litellm.ai/docs/providers\", \"mode\": \"one of chat, embedding, completion, image generation, audio transcription, audio speech\", \"supports function calling\": true, \"supports parallel function calling\": true, \"supports vision\": true… 证据：`ragaai_catalyst/tracers/utils/model_prices_and_context_window_backup.json`\n- **Byte-compiled / optimized / DLL files**（source_file）：.idea/ dist/ test files ragaai catalyst.egg-info/ .DS Store test files/ pycache / /model costs.json .vscode 证据：`.gitignore`\n- **license = {file = \"LICENSE\"}**（source_file）：build-system requires = \"setuptools =45\", \"wheel\", \"setuptools scm =6.2\" build-backend = \"setuptools.build meta\" 证据：`pyproject.toml`\n- **Init**（source_file）：from .experiment import Experiment from .ragaai catalyst import RagaAICatalyst from .utils import response checker from .dataset import Dataset from .prompt manager import PromptManager from .evaluation import Evaluation from .synthetic data generation import SyntheticDataGeneration from .redteaming import RedTeaming from .guardrails manager import GuardrailsManager from .guard executor import GuardExecutor from .tracers import Tracer, init tracing, trace agent, trace llm, trace tool, current span, trace custom from .redteaming import RedTeaming 证据：`ragaai_catalyst/__init__.py`\n- **file generated by setuptools scm**（source_file）：file generated by setuptools scm don't change, don't track in version control TYPE CHECKING = False if TYPE CHECKING: from typing import Tuple, Union VERSION TUPLE = Tuple Union int, str , ... else: VERSION TUPLE = object 证据：`ragaai_catalyst/_version.py`\n- **Job status constants**（source_file）：import os import csv import json import tempfile import requests from .utils import response checker from typing import Union import logging from .ragaai catalyst import RagaAICatalyst import pandas as pd logger = logging.getLogger name get token = RagaAICatalyst.get token 证据：`ragaai_catalyst/dataset.py`\n- **Job status constants**（source_file）：import os import requests import pandas as pd import io from .ragaai catalyst import RagaAICatalyst import logging import json 证据：`ragaai_catalyst/evaluation.py`\n- **logger.debug \"Projects list retrieved successfully\"**（source_file）：import os import requests import logging import pandas as pd from .utils import response checker from .ragaai catalyst import RagaAICatalyst 证据：`ragaai_catalyst/experiment.py`\n- **check if 2 deployments are mapped to same dataset**（source_file）：import litellm import json import requests import os from google import genai from google.genai.types import GenerateContentConfig from typing import Optional, List, Dict, Any import logging logger = logging.getLogger 'LiteLLM' logger.setLevel logging.ERROR 证据：`ragaai_catalyst/guard_executor.py`\n- **Check if dataset name exists**（source_file）：import requests import json import os import logging logger = logging.getLogger name from .utils import response checker from .ragaai catalyst import RagaAICatalyst 证据：`ragaai_catalyst/guardrails_manager.py`\n- **'Wd-PCA-Feature-Key':f'your feature key, $ whoami '**（source_file）：import requests import json import subprocess import logging import traceback import pandas as pd 证据：`ragaai_catalyst/internal_api_completion.py`\n- **logger.debug \"Projects list retrieved successfully\"**（source_file）：import os import requests import json import re from .ragaai catalyst import RagaAICatalyst import copy 证据：`ragaai_catalyst/prompt_manager.py`\n- **logger.error f'Error in model response Job ID {job id}:',str response.text**（source_file）：import requests import json import subprocess import logging import traceback 证据：`ragaai_catalyst/proxy_call.py`\n- **set the os.environ \"RAGAAI CATALYST BASE URL\" before getting the token as it is used in the get token method**（source_file）：import os import logging import requests import time from typing import Dict, Optional, Union import re logger = logging.getLogger \"RagaAICatalyst\" logging level = logger.setLevel logging.DEBUG if os.getenv \"DEBUG\" == \"1\" else logging.INFO 证据：`ragaai_catalyst/ragaai_catalyst.py`\n- **import logging**（source_file）：import logging import os from typing import Callable, Optional 证据：`ragaai_catalyst/redteaming_old.py`\n- **Initialize the appropriate client based on provider**（source_file）：import os import ast import csv import json import random import pypdf import markdown import pandas as pd from tqdm import tqdm 证据：`ragaai_catalyst/synthetic_data_generation.py`\n- **Set up logging**（source_file）：import os import requests import logging 证据：`ragaai_catalyst/utils.py`\n- **Requirements**（source_file）：aiohappyeyeballs==2.4.4 aiohttp==3.10.11 aiosignal==1.3.2 annotated-types==0.7.0 anyio==4.7.0 attrs==24.3.0 beautifulsoup4==4.12.3 cachetools==5.5.0 certifi==2024.12.14 charset-normalizer==3.4.0 click==8.1.8 Deprecated==1.2.15 distro==1.9.0 filelock==3.16.1 frozenlist==1.5.0 fsspec==2024.12.0 google-genai =1.3.0 google==3.0.0 google-ai-generativelanguage==0.6.10 google-api-core==2.24.0 google-api-python-client==2.156.0 google-auth==2.37.0 google-auth-httplib2==0.2.0 google-generativeai==0.8.3 googleapis-common-protos==1.66.0 groq==0.13.1 grpcio==1.68.1 grpcio-status==1.68.1 h11==0.14.0 httpcore==1.0.7 httplib2==0.22.0 httpx==0.28.1 huggingface-hub==0.27.0 idna==3.10 importlib metadata==7.1.… 证据：`requirements.txt`\n- **Test Report 20250407 183101**（source_file）：TEST EXECUTION REPORT ===================== Date: 2025-04-07 18:31:01 证据：`test_report_20250407_183101.txt`\n- **Environment**（source_file）：name: ragaai pytest env channels: - conda-forge - defaults - https://repo.anaconda.com/pkgs/main - https://repo.anaconda.com/pkgs/r dependencies: - anaconda-anon-usage=0.5.0=py312hd6b623d 100 - archspec=0.2.3=pyhd3eb1b0 0 - boltons=24.1.0=py312hca03da5 0 - brotli-python=1.0.9=py312h313beb8 9 - bzip2=1.0.8=h80987f9 6 - c-ares=1.19.1=h80987f9 0 - ca-certificates=2025.1.31=hf0a4a13 0 - certifi=2025.1.31=pyhd8ed1ab 0 - cffi=1.17.1=py312h3eb5a62 1 - conda=25.3.1=py312h81bd7bf 0 - conda-anaconda-telemetry=0.1.2=py312hca03da5 0 - conda-anaconda-tos=0.1.2=py312hca03da5 0 - conda-content-trust=0.2.0=py312hca03da5 1 - conda-libmamba-solver=25.1.1=pyhd3eb1b0 0 - conda-package-handling=2.4.0=py312hca03… 证据：`tests/environment.yml`\n- **Match lines like:**（source_file）：from datetime import datetime from tabulate import tabulate import re from typing import List, Dict import subprocess import os 证据：`tests/run_pytest_and_print_and_save_results.py`\n- **Tests Requirements**（source_file）：vertexai =1.38.1 google-generativeai =0.5.2 anthropic =0.18.0 langchain-google-genai =0.1.2 langchain-google-vertexai =0.1.2 crewai haystack-ai =2.0.0 langchain-community =0.0.29 langgraph =0.0.31 pypdf2 =3.0.1 arxiv =2.1.3 smolagents =1.13.0 sentence-transformers =4.0.2 langchain-openai 证据：`tests_requirements.txt`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `tests/README.md`, `examples/crewai/scifi_writer/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `tests/README.md`, `examples/crewai/scifi_writer/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **安装与快速开始**：importance `high`\n - source_paths: README.md, pyproject.toml, requirements.txt, quickstart.md\n- **配置与认证**：importance `high`\n - source_paths: ragaai_catalyst/ragaai_catalyst.py, examples/all_llm_provider/config.py, examples/custom_agents/travel_agent/config.py\n- **项目管理**：importance `high`\n - source_paths: ragaai_catalyst/ragaai_catalyst.py, ragaai_catalyst/__init__.py\n- **数据集管理**：importance `high`\n - source_paths: ragaai_catalyst/dataset.py, docs/dataset_management.md\n- **评估管理**：importance `high`\n - source_paths: ragaai_catalyst/evaluation.py, ragaai_catalyst/experiment.py\n- **提示词管理**：importance `medium`\n - source_paths: ragaai_catalyst/prompt_manager.py, docs/prompt_management.md\n- **智能体追踪系统**：importance `high`\n - source_paths: ragaai_catalyst/tracers/agentic_tracing/__init__.py, ragaai_catalyst/tracers/agentic_tracing/tracers/base.py, ragaai_catalyst/tracers/agentic_tracing/data/data_structure.py, docs/agentic_tracing.md\n- **追踪器类型与框架支持**：importance `high`\n - source_paths: ragaai_catalyst/tracers/tracer.py, ragaai_catalyst/tracers/agentic_tracing/tracers/langgraph_tracer.py, ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py, ragaai_catalyst/tracers/agentic_tracing/tracers/tool_tracer.py, docs/trace_management.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `ab67893310891140211280a496402003e52cdab5`\n- inspected_files: `pyproject.toml`, `README.md`, `requirements.txt`, `docs/trace_management.md`, `docs/dataset_management.md`, `docs/agentic_tracing.md`, `docs/prompt_management.md`, `examples/all_llm_provider/all_llm_provider.py`, `examples/all_llm_provider/run_all_llm_provider.py`, `examples/all_llm_provider/config.py`, `examples/haystack/news_fetching/news_fetching.py`, `examples/haystack/news_fetching/README.md`, `examples/llamaindex_examples/legal_research_rag/legal_rag.py`, `examples/pii_masking_example/llamaindex_agentic_fastapi/app_presidio.py`, `examples/pii_masking_example/llamaindex_agentic_fastapi/request.py`, `examples/pii_masking_example/llamaindex_agentic_fastapi/app.py`, `examples/smolagents/most_upvoted_paper/README.md`, `examples/smolagents/most_upvoted_paper/most_upvoted_paper.py`, `examples/openai_agents_sdk/youtube_summary_agent/youtube_summary_agent.py`, `examples/openai_agents_sdk/youtube_summary_agent/README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：2.1.7.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：2.1.6\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：2.2.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：2.2.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v2.1.5\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：raga-ai-hub/RagaAI-Catalyst\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：2.1.7.1（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：2.1.6（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/raga-ai-hub/RagaAI-Catalyst 项目说明书\n\n生成时间：2026-05-21 05:24:17 UTC\n\n## 目录\n\n- [安装与快速开始](#installation)\n- [配置与认证](#configuration)\n- [项目管理](#project-management)\n- [数据集管理](#dataset-management)\n- [评估管理](#evaluation)\n- [提示词管理](#prompt-management)\n- [智能体追踪系统](#agentic-tracing)\n- [追踪器类型与框架支持](#tracer-types)\n- [合成数据生成](#synthetic-data)\n- [安全护栏管理](#guardrails)\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[配置与认证](#configuration), [项目管理](#project-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/requirements.txt)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n \n\n# 安装与快速开始\n\n## 概述\n\nRagaAI Catalyst 是一个企业级 MLOps 和 LLM 应用监控平台，提供完整的模型生命周期管理能力。该平台支持项目创建、数据集管理、应用追踪、提示词管理、合成数据生成、护栏管理和红队测试等核心功能。资料来源：[README.md:1-15]()\n\n本页面将指导用户完成 RagaAI Catalyst SDK 的完整安装流程、认证配置以及基础使用示例，帮助开发者快速上手使用该平台进行 LLM 应用的开发与监控。\n\n---\n\n## 安装前置条件\n\n### 系统要求\n\n| 要求类型 | 最低版本 |\n|---------|---------|\n| Python | 3.10+ |\n| pip | 最新版本 |\n| 内存 | 4GB+ |\n| 网络 | 需要访问 RagaAI Catalyst 服务端点 |\n\n### 依赖环境\n\nRagaAI Catalyst SDK 依赖以下核心包：\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|-----|\n| openai | >=1.0.0 | OpenAI API 集成 |\n| pandas | >=2.0.0 | 数据处理 |\n| opentelemetry-api | >=1.25.0 | 追踪 instrumentation |\n| opentelemetry-sdk | >=1.25.0 | SDK 核心功能 |\n| litellm | >=1.61.15 | 多模型调用支持 |\n\n完整依赖列表请参考 `requirements.txt` 文件。资料来源：[requirements.txt:1-50]()\n\n---\n\n## 安装方式\n\n### 方式一：pip 直接安装（推荐）\n\n使用 pip 包管理器直接安装是最简便的方式：\n\n```bash\npip install ragaai-catalyst\n```\n\n资料来源：[README.md:20]()\n\n### 方式二：从源码安装\n\n如需安装最新开发版本或进行二次开发，可从源码安装：\n\n```bash\ngit clone https://github.com/raga-ai-hub/RagaAI-Catalyst.git\ncd RagaAI-Catalyst\npip install -e .\n```\n\n### 方式三：开发环境安装\n\n如果需要安装包含所有可选依赖的开发环境：\n\n```bash\npip install -r requirements.txt\n```\n\n资料来源：[tests_requirements.txt:1-15]()\n\n---\n\n## 认证配置\n\n### 获取 API 密钥\n\n使用 RagaAI Catalyst 前必须完成认证配置。获取密钥的步骤如下：\n\n1. 登录 [RagaAI Catalyst 平台](https://catalyst.raga.ai/)\n2. 进入 **Profile Settings** → **Authentication**\n3. 点击 **Generate New Key** 创建新的访问密钥\n4. 复制生成的 **Access Key** 和 **Secret Key**\n\n资料来源：[README.md:25-35]()\n\n\n\n### 初始化 SDK\n\n在 Python 代码中初始化 RagaAICatalyst 客户端：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\", # 替换为您的访问密钥\n secret_key=\"YOUR_SECRET_KEY\", # 替换为您的密钥\n base_url=\"BASE_URL\" # 替换为服务基地址\n)\n```\n\n资料来源：[README.md:36-45]()\n\n---\n\n## 快速开始工作流\n\n以下流程图展示了使用 RagaAI Catalyst 的基本工作顺序：\n\n```mermaid\ngraph TD\n A[安装 ragaai-catalyst] --> B[配置认证密钥]\n B --> C[创建项目]\n C --> D[添加数据集]\n D --> E[集成追踪功能]\n E --> F[运行应用]\n F --> G[查看评估结果]\n \n style A fill:#e1f5fe\n style G fill:#c8e6c9\n```\n\n---\n\n## 创建第一个项目\n\n### 项目创建示例\n\n创建项目时需要指定项目名称和用例类型：\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"Test-RAG-App-1\",\n usecase=\"Chatbot\" # 可选值: Chatbot, Q/A, Others, Agentic Application\n)\n\n# 获取可用用例列表\nprint(catalyst.project_use_cases())\n\n# 列出所有项目\nprojects = catalyst.list_projects()\nprint(projects)\n```\n\n资料来源：[README.md:50-65]()\n\n### 支持的用例类型\n\n| 用例类型 | 说明 |\n|---------|-----|\n| Chatbot | 聊天机器人应用 |\n| Q/A | 问答系统 |\n| Others | 其他类型应用 |\n| Agentic Application | 智能体应用 |\n\n---\n\n## 数据集管理\n\n### 创建数据集\n\n支持从 CSV 文件创建数据集，需要定义 schema mapping：\n\n```python\nfrom ragaai_catalyst import Dataset\n\n# 初始化数据集管理器\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 从 CSV 文件创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"MyDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n\n# 查看数据集 schema\nprint(dataset_manager.get_schema_mapping())\n```\n\n资料来源：[README.md:70-90]()\n\n### Schema Mapping 配置说明\n\n| Schema 元素 | 说明 |\n|------------|-----|\n| Query/prompt | 用户输入查询 |\n| response | 模型响应 |\n| Context | 上下文信息 |\n| expectedResponse | 期望的标准响应 |\n\n---\n\n## 应用追踪配置\n\n### 自动注入追踪\n\n支持多种智能体框架的自动追踪：\n\n```python\nfrom ragaai_catalyst import init_tracing, Tracer\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\" # 选择对应的框架类型\n)\n\n# 启用自动注入\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[quickstart.md:30-45]()\n\n### 支持的追踪器类型\n\n| 追踪器类型 | 框架支持 |\n|-----------|---------|\n| agentic/langgraph | LangGraph |\n| agentic/langchain | LangChain |\n| agentic/smolagents | SmoLAgents |\n| agentic/openai_agents | OpenAI Agents |\n| agentic/llamaindex | LlamaIndex |\n| agentic/haystack | Haystack |\n| agentic/crewai | CrewAI |\n| rag/langchain | RAG + LangChain |\n\n资料来源：[quickstart.md:55-65]()\n\n### 自定义追踪\n\n```python\nfrom ragaai_catalyst import Tracer\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"tracer_type\"\n)\n\n# 方式一：使用 with 语句\nwith tracer():\n # 您的应用代码\n pass\n\n# 方式二：手动控制\ntracer.start()\n# 您的应用代码\ntracer.stop()\n\n# 查看上传状态\nprint(tracer.get_upload_status())\n```\n\n---\n\n## 提示词管理\n\n### PromptManager 使用\n\n```python\nfrom ragaai_catalyst import PromptManager\n\n# 初始化提示词管理器\nprompt_manager = PromptManager(project_name=\"Test-RAG-App-1\")\n\n# 列出可用提示词\nprompts = prompt_manager.list_prompts()\nprint(\"Available prompts:\", prompts)\n\n# 获取指定提示词\nprompt = prompt_manager.get_prompt(\"your_prompt_name\")\n\n# 获取提示词内容\nprompt_content = prompt.get_prompt_content()\nprint(\"prompt_content:\", prompt_content)\n\n# 获取提示词变量\nvariables = prompt.get_variables()\nprint(\"variables:\", variables)\n\n# 编译提示词\ncompiled_prompt = prompt.compile(\n query=\"What's the weather?\",\n context=\"sunny\",\n llm_response=\"It's sunny today\"\n)\n```\n\n资料来源：[README.md:120-145]()\n\n---\n\n## 示例代码\n\n### SmoLAgents 示例\n\n安装示例依赖后运行：\n\n```bash\npip install -r requirements.txt\n```\n\n```python\nfrom most_upvoted_paper import main\n\n# 运行论文摘要管道\nmain()\n```\n\n该示例展示如何使用 SmoLAgents 框架下载论文并生成摘要。资料来源：[examples/smolagents/most_upvoted_paper/README.md:1-25]()\n\n### CrewAI 示例\n\n完整的 CrewAI 应用追踪示例：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom crewai import Agent, Task, Crew, Process\nfrom crewai.tools import tool\n\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'), \n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'), \n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 定义 CrewAI agents 和 tasks...\ncrew = Crew(\n agents=[brainstormer, outliner, writer],\n tasks=[brainstorm_task, outline_task, writing_task],\n process=Process.sequential,\n verbose=True\n)\n\nresult = crew.kickoff()\n```\n\n---\n\n## 常见问题\n\n### 环境变量配置\n\n建议使用 `.env` 文件管理敏感信息：\n\n```bash\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key\nRAGAAI_CATALYST_BASE_URL=your_base_url\nRAGAAI_PROJECT_NAME=your_project_name\nRAGAAI_DATASET_NAME=your_dataset_name\n```\n\n### 导入问题\n\n如遇到导入错误，请确保：\n\n1. 已正确安装 `ragaai-catalyst` 包\n2. Python 版本符合要求（3.10+）\n3. 所有依赖包已正确安装\n\n---\n\n## 下一步\n\n完成安装和快速开始后，您可以：\n\n- 深入了解[评估框架](./evaluation_framework.md)的使用\n- 探索[红队测试](./red_teaming.md)功能\n- 配置[护栏管理](./guardrails.md)规则\n- 学习[合成数据生成](./synthetic_data.md)技术\n\n---\n\n\n\n## 配置与认证\n\n### 相关页面\n\n相关主题：[安装与快速开始](#installation), [智能体追踪系统](#agentic-tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/ragaai_catalyst.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 配置与认证\n\n## 概述\n\nRagaAI Catalyst 的配置与认证系统是整个平台的基础模块，负责管理用户身份验证、凭证存储以及与后端服务的安全通信。所有使用 RagaAI Catalyst 功能之前必须完成正确的配置和身份认证。\n\n核心认证流程通过 `RagaAICatalyst` 类实现，该类封装了所有与平台服务的交互逻辑，支持通过环境变量或直接传入参数两种方式进行配置。\n\n## 认证凭证获取\n\n### 获取步骤\n\n1. 登录 [RagaAI Catalyst](https://catalyst.raga.ai/) 账户\n2. 进入 **Profile Settings** → **Authentication** 页面\n3. 点击 **Generate New Key** 生成新的访问密钥\n\n认证成功后，用户将获得以下凭证信息：\n\n| 凭证类型 | 用途 | 必要性 |\n|---------|------|--------|\n| Access Key | 标识用户身份 | 必须 |\n| Secret Key | 验证用户身份 | 必须 |\n| Base URL | API 端点地址 | 必须 |\n\n## SDK 初始化配置\n\n### 基本初始化\n\n使用 `RagaAICatalyst` 类进行 SDK 初始化是最基础的配置方式：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\", # 用户访问密钥\n secret_key=\"YOUR_SECRET_KEY\", # 用户密钥\n base_url=\"BASE_URL\" # 服务端点\n)\n```\n\n### 环境变量配置\n\n在生产环境中，推荐使用环境变量存储敏感凭证，避免硬编码：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst\n\n# 加载 .env 文件中的环境变量\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n```\n\n典型 `.env` 文件配置：\n\n```env\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key_here\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key_here\nRAGAAI_CATALYST_BASE_URL=https://api.raga.ai/catalyst\n```\n\n## 追踪功能配置\n\n### Tracer 初始化\n\n追踪系统需要单独配置 `Tracer` 类，与主 SDK 配合使用：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 1. 初始化主 SDK\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 2. 初始化追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\" # 支持多种追踪类型\n)\n\n# 3. 启用自动追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### Tracer 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| project_name | string | 必填 | 项目名称 |\n| dataset_name | string | 必填 | 数据集名称 |\n| trace_name | string | None | 追踪名称 |\n| tracer_type | string | None | 追踪器类型 |\n| timeout | int | 120 | 超时时间（秒） |\n| update_llm_cost | bool | True | 是否更新模型成本 |\n| max_upload_workers | int | 30 | 最大上传并发数 |\n\n### 自动仪表化配置\n\n可通过 `auto_instrumentation` 参数控制各组件的自动追踪：\n\n```python\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\",\n auto_instrumentation={\n 'llm': True, # LLM 调用追踪\n 'tool': True, # 工具调用追踪\n 'agent': True, # Agent 追踪\n 'user_interaction': True, # 用户交互追踪\n 'file_io': True, # 文件操作追踪\n 'network': True, # 网络请求追踪\n 'custom': True # 自定义事件追踪\n }\n)\n```\n\n## 支持的追踪器类型\n\nRagaAI Catalyst 支持多种框架的追踪集成：\n\n| tracer_type | 框架 | 说明 |\n|-------------|------|------|\n| agentic/langgraph | LangGraph | 图结构工作流追踪 |\n| agentic/langchain | LangChain | LangChain 框架追踪 |\n| agentic/smolagents | SmolAgents | 轻量级 Agent 追踪 |\n| agentic/openai_agents | OpenAI Agents | OpenAI Agent SDK |\n| agentic/llamaindex | LlamaIndex | 索引和查询追踪 |\n| agentic/haystack | Haystack | NLP 管道追踪 |\n| agentic/crewai | CrewAI | 多 Agent 协作追踪 |\n| rag/langchain | LangChain RAG | RAG 应用追踪 |\n\n## 配置架构\n\n```mermaid\ngraph TD\n A[应用程序] --> B[环境变量 / .env]\n B --> C[RagaAICatalyst 初始化]\n C --> D[认证服务验证]\n D --> E{验证结果}\n E -->|成功| F[创建项目 / 管理数据集]\n E -->|失败| G[认证错误]\n F --> H[Tracer 初始化]\n H --> I[init_tracing 启用追踪]\n I --> J[追踪数据上传]\n \n K[手动配置] --> C\n style G fill:#ffcccc\n```\n\n## 典型配置流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant App as 应用程序\n participant Env as 环境变量\n participant SDK as RagaAICatalyst\n participant API as RagaAI API\n \n User->>API: 1. 生成认证密钥\n API->>User: 返回 access_key, secret_key\n User->>Env: 2. 配置环境变量\n App->>Env: 3. 加载环境变量\n App->>SDK: 4. 初始化 SDK\n SDK->>API: 5. 验证凭证\n API-->>SDK: 验证成功\n SDK-->>App: SDK 实例就绪\n App->>SDK: 6. 创建 Tracer\n SDK->>API: 7. 注册追踪器\n App->>SDK: 8. 调用 init_tracing\n SDK->>API: 9. 启用数据采集\n```\n\n## 项目级配置\n\n除了全局 SDK 配置外，RagaAI Catalyst 还支持项目级别的配置管理：\n\n```python\n# 创建项目时指定用例类型\nproject = catalyst.create_project(\n project_name=\"My-RAG-App\",\n usecase=\"Q/A\" # 可选值: Chatbot, Q/A, Others, Agentic Application\n)\n\n# 查看可用的用例类型\nprint(catalyst.project_use_cases())\n\n# 列出所有项目\nprojects = catalyst.list_projects()\n```\n\n## 数据集配置\n\n数据集管理同样需要正确的项目配置：\n\n```python\nfrom ragaai_catalyst import Dataset\n\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 从 CSV 创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"MyDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n```\n\n## 安全建议\n\n| 建议 | 说明 |\n|------|------|\n| 使用环境变量 | 避免在代码中硬编码敏感凭证 |\n| 使用 .env 文件 | 使用 `python-dotenv` 管理环境配置 |\n| 定期轮换密钥 | 定期更换 Access Key 和 Secret Key |\n| 最小权限原则 | 仅授予必要的 API 访问权限 |\n| 密钥存储 | 生产环境使用密钥管理服务（如 AWS Secrets Manager） |\n\n## 常见错误处理\n\n认证配置过程中可能遇到的常见错误：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| InvalidCredentials | 密钥格式错误或已过期 | 重新生成认证密钥 |\n| NetworkError | 网络连接问题 | 检查网络代理和防火墙设置 |\n| Unauthorized | 密钥权限不足 | 检查 API 密钥的访问范围 |\n| TimeoutError | 服务响应超时 | 增加 timeout 参数值 |\n\n## 完整示例\n\n以下是一个完整的配置与认证示例：\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 加载环境变量\nload_dotenv()\n\n# 初始化主 SDK\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\"\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 创建项目\nproject = catalyst.create_project(\n project_name=\"Test-Project\",\n usecase=\"Agentic Application\"\n)\n```\n\n## 相关文档\n\n- [快速开始指南](quickstart.md) - 完整的快速入门教程\n- [追踪管理](./tracing.md) - 详细的追踪功能说明\n- [评估框架](./evaluation.md) - 评估功能配置\n- [项目与数据集管理](./project_dataset.md) - 项目和数据集操作\n\n---\n\n\n\n## 项目管理\n\n### 相关页面\n\n相关主题：[数据集管理](#dataset-management), [评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n \n\n# 项目管理\n\n## 概述\n\n项目管理是 RagaAI Catalyst 平台的核心功能模块，用于组织和管理 AI 应用的全生命周期。通过项目管理功能，用户可以创建不同类型的 AI 应用项目、管理相关数据集、配置追踪器、运行评估任务以及执行红队测试。\n\nRagaAI Catalyst 的项目管理采用分层架构设计，核心入口为 `RagaAICatalyst` 类，通过该类可以访问所有项目管理相关功能。资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 核心架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[RagaAICatalyst 客户端]\n B --> C[项目管理]\n B --> D[数据集管理]\n B --> E[追踪管理]\n B --> F[评估管理]\n B --> G[提示词管理]\n B --> H[红队测试]\n \n C --> I[创建项目]\n C --> J[列举项目]\n C --> K[使用案例配置]\n \n D --> L[CSV 上传]\n D --> M[DataFrame 上传]\n D --> N[JSONL 上传]\n \n E --> O[LangGraph 追踪]\n E --> P[LangChain 追踪]\n E --> Q[其他框架追踪]\n```\n\n### 客户端初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Env as 环境变量\n participant Catalyst as RagaAICatalyst\n \n User->>Env: 设置认证凭证\n User->>Catalyst: 初始化客户端\n Catalyst->>Catalyst: 验证凭证\n Catalyst-->>User: 返回客户端实例\n```\n\n## 客户端初始化\n\n### 基本配置\n\n使用 RagaAI Catalyst 之前，必须先初始化 `RagaAICatalyst` 客户端实例。客户端支持通过环境变量或直接传入参数两种方式进行配置。资料来源：[README.md:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n```\n\n### 环境变量配置方式\n\n在实际项目中，推荐使用环境变量方式配置认证信息，便于管理敏感凭证。资料来源：[examples/custom_agents/travel_agent/config.py:1-20](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n### 初始化参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| access_key | str | 是 | 访问密钥，从 RagaAI Catalyst 平台获取 |\n| secret_key | str | 是 | 秘密密钥，从 RagaAI Catalyst 平台获取 |\n| base_url | str | 是 | API 基础 URL，根据部署环境配置 |\n\n### 获取认证密钥\n\n1. 登录 RagaAI Catalyst 平台 (https://catalyst.raga.ai/)\n2. 进入个人资料设置 (Profile Settings)\n3. 选择身份验证 (Authentication) 选项卡\n4. 点击生成新密钥 (Generate New Key) 创建访问密钥和秘密密钥\n\n资料来源：[quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n\n## 项目创建与管理\n\n### 创建新项目\n\n使用 `create_project` 方法创建新项目，需要指定项目名称和用例类型。资料来源：[README.md:35-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"Test-RAG-App-1\",\n usecase=\"Chatbot\" # 用例类型\n)\n\n# 获取可用用例列表\nprint(catalyst.project_use_cases())\n```\n\n### 支持的用例类型\n\n| 用例类型 | 说明 | 适用场景 |\n|----------|------|----------|\n| Chatbot | 聊天机器人 | 对话式 AI 应用 |\n| Q/A | 问答系统 | 知识问答、RAG 应用 |\n| Others | 其他 | 自定义 AI 应用 |\n| Agentic Application | 代理应用 | 自主代理、多步骤任务 |\n\n### 列举项目\n\n```python\n# 列出所有项目\nprojects = catalyst.list_projects()\nprint(projects)\n```\n\n## 追踪器与项目集成\n\n项目管理与追踪系统紧密集成，每个项目可以配置专属的追踪器用于监控应用行为。资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-25](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n\n### 追踪器初始化\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化 Catalyst 客户端\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'), \n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'), \n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建项目级追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### 追踪器类型对照表\n\n| tracer_type 参数 | 支持框架 | 说明 |\n|------------------|----------|------|\n| agentic/langgraph | LangGraph | LangGraph 框架追踪 |\n| agentic/langchain | LangChain | LangChain 框架追踪 |\n| agentic/smolagents | SmolAgents | SmolAgents 框架追踪 |\n| agentic/openai_agents | OpenAI Agents | OpenAI Agents SDK 追踪 |\n| agentic/llamaindex | LlamaIndex | LlamaIndex 框架追踪 |\n| agentic/haystack | Haystack | Haystack 框架追踪 |\n| agentic/crewai | CrewAI | CrewAI 框架追踪 |\n\n资料来源：[examples/langgraph/personal_research_assistant/research_assistant.py:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n\n### 完整配置示例\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\nload_dotenv()\n\ndef initialize_tracing():\n \"\"\"初始化追踪配置\"\"\"\n catalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n )\n\n tracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\",\n )\n\n init_tracing(catalyst=catalyst, tracer=tracer)\n return tracer\n```\n\n## 项目相关组件\n\n### 组件关系图\n\n```mermaid\ngraph LR\n A[项目 Project] --> B[数据集 Dataset]\n A --> C[追踪器 Tracer]\n A --> D[评估 Evaluation]\n A --> E[提示词 Prompt]\n A --> F[红队测试]\n \n B --> B1[Schema Mapping]\n B --> B2[数据源]\n \n C --> C1[追踪数据]\n C --> C2[执行记录]\n \n D --> D1[评估指标]\n D --> D2[评估结果]\n```\n\n### 各组件功能说明\n\n| 组件名称 | 功能描述 | 主要方法 |\n|----------|----------|----------|\n| Dataset | 数据集管理 | create_from_csv, get_schema_mapping |\n| Tracer | 执行追踪 | start, stop, get_upload_status |\n| Evaluation | 模型评估 | add_metrics, get_status, get_results |\n| PromptManager | 提示词管理 | list_prompts, get_prompt, compile |\n| RedTeaming | 红队测试 | run, detectors |\n\n## 环境变量配置\n\n### 必需环境变量\n\n| 环境变量名 | 说明 | 示例值 |\n|------------|------|--------|\n| RAGAAI_CATALYST_ACCESS_KEY | 访问密钥 | sk-xxx |\n| RAGAAI_CATALYST_SECRET_KEY | 秘密密钥 | sk-xxx |\n| RAGAAI_CATALYST_BASE_URL | API 地址 | https://api.catalyst.raga.ai |\n| RAGAAI_PROJECT_NAME | 项目名称 | my-project |\n| RAGAAI_DATASET_NAME | 数据集名称 | my-dataset |\n\n### .env 文件配置示例\n\n```bash\nRAGAAI_CATALYST_ACCESS_KEY=your_access_key_here\nRAGAAI_CATALYST_SECRET_KEY=your_secret_key_here\nRAGAAI_CATALYST_BASE_URL=https://api.catalyst.raga.ai\nRAGAAI_PROJECT_NAME=Test-Project\nRAGAAI_DATASET_NAME=Test-Dataset\n```\n\n## 典型使用流程\n\n### 完整项目生命周期流程\n\n```mermaid\ngraph TD\n A[初始化客户端] --> B[创建项目]\n B --> C[配置用例类型]\n C --> D[创建数据集]\n D --> E[初始化追踪器]\n E --> F[开发应用代码]\n F --> G[运行评估]\n G --> H{评估结果}\n H -->|通过| I[部署上线]\n H -->|失败| J[问题修复]\n J --> F\n```\n\n### 分步操作示例\n\n**步骤 1: 初始化和认证**\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n**步骤 2: 创建和管理项目**\n\n```python\n# 创建新项目\nproject = catalyst.create_project(\n project_name=\"My-RAG-Application\",\n usecase=\"Q/A\"\n)\n\n# 查看可用用例\nuse_cases = catalyst.project_use_cases()\n\n# 列举所有项目\nall_projects = catalyst.list_projects()\n```\n\n**步骤 3: 集成追踪功能**\n\n```python\nfrom ragaai_catalyst import init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ntracer = Tracer(\n project_name=\"My-RAG-Application\",\n dataset_name=\"production-traces\",\n tracer_type=\"agentic/langgraph\",\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n## 最佳实践\n\n### 1. 项目组织建议\n\n- 按业务线或应用类型划分项目\n- 为每个项目配置独立的数据集和追踪器\n- 使用清晰的项目命名规范\n\n### 2. 认证安全建议\n\n- 敏感凭证使用环境变量管理\n- 避免在代码中硬编码密钥\n- 定期轮换访问密钥\n\n### 3. 追踪配置建议\n\n- 根据应用框架选择正确的 tracer_type\n- 为生产环境和开发环境使用不同的数据集\n- 定期检查追踪数据上传状态\n\n## 依赖要求\n\n项目管理的 Python 依赖已包含在主包中，核心依赖包括：\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|----------|------|\n| openai | >=1.0.0 | OpenAI API 集成 |\n| pandas | >=2.0.0 | 数据处理 |\n| dotenv | 最新版 | 环境变量管理 |\n\n额外测试依赖见 [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n\n## 常见问题\n\n### Q: 如何获取认证密钥？\n\n登录 RagaAI Catalyst 平台，进入 Profile Settings → Authentication，点击 Generate New Key 获取。\n\n### Q: tracer_type 有哪些可选值？\n\n支持 agentic/langgraph、agentic/langchain、agentic/smolagents、agentic/openai_agents、agentic/llamaindex、agentic/haystack 等类型。\n\n### Q: 项目和数据集是什么关系？\n\n一个项目可以包含多个数据集，数据集用于存储评估用的测试数据和追踪记录。\n\n---\n\n\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[项目管理](#project-management), [评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 数据集管理\n\n## 概述\n\nRagaAI Catalyst 的数据集管理模块为用户提供了统一的数据集创建、查询和元数据管理能力。该模块支持从 CSV 文件、DataFrame 或 JSONL 文件导入数据集，并提供了灵活的模式映射（Schema Mapping）功能，使用户能够将数据列映射到系统定义的标准模式元素。\n\n数据集管理在 RagaAI Catalyst 平台中扮演着数据入口的角色，是后续追踪（Tracing）和评估（Evaluation）功能的基础前提。只有在项目下创建了有效的数据集，用户才能配置追踪器捕获应用行为，或运行评估指标分析应用性能。\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 核心类与导入\n\n数据集管理的核心功能通过 `Dataset` 类实现，该类封装了所有与数据集操作相关的接口。\n\n```python\nfrom ragaai_catalyst import Dataset\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 初始化 Dataset 管理器\n\n在使用任何数据集操作之前，需要先初始化 `Dataset` 管理器实例。初始化时必须指定项目名称，以便在对应的项目上下文中管理数据集。\n\n```python\ndataset_manager = Dataset(project_name=\"project_name\")\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 主要功能\n\n### 列出已有数据集\n\n用户可以通过 `list_datasets()` 方法查看指定项目下所有已创建的数据集。\n\n```python\ndatasets = dataset_manager.list_datasets()\nprint(\"Existing Datasets:\", datasets)\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n### 从 CSV 文件创建数据集\n\n`create_from_csv()` 方法允许用户从本地 CSV 文件导入数据创建数据集。该方法需要提供文件路径、数据集名称以及列映射配置。\n\n```python\ndataset_manager.create_from_csv(\n csv_path='path/to/your.csv',\n dataset_name='MyDataset',\n schema_mapping={'column1': 'schema_element1', 'column2': 'schema_element2'}\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md) 和 [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n### 获取模式映射\n\n创建数据集时定义的模式映射可以通过 `get_schema_mapping()` 方法查询，用于验证数据列与系统模式元素的对应关系。\n\n```python\nprint(dataset_manager.get_schema_mapping())\n```\n\n资料来源：[README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n\n## 模式映射（Schema Mapping）\n\n模式映射是数据集创建过程中的核心配置项，用于将用户数据中的列名映射到 RagaAI Catalyst 平台定义的标准化模式元素。\n\n### 标准模式元素\n\n根据评估框架的使用示例，典型的模式映射结构如下：\n\n| 用户数据列 | 标准模式元素 | 说明 |\n|------------|--------------|------|\n| Query / prompt | 提示词 | 用户的输入查询 |\n| response | 响应 | 模型的返回结果 |\n| Context / context | 上下文 | RAG 应用的检索上下文 |\n| expectedResponse / expected_response | 期望响应 | 用于评估的参考答案 |\n\n```python\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 数据集管理流程\n\n```mermaid\ngraph TD\n A[初始化 Dataset 管理器] --> B{数据源类型}\n B -->|CSV 文件| C[调用 create_from_csv]\n B -->|DataFrame| D[调用 create_from_dataframe]\n B -->|JSONL 文件| E[调用 create_from_jsonl]\n C --> F[定义 schema_mapping]\n D --> F\n E --> F\n F --> G[创建数据集]\n G --> H[验证模式映射]\n H --> I[数据集可用于评估和追踪]\n```\n\n## 在评估框架中的使用\n\n数据集创建完成后，可以与评估框架集成，用于运行各种评估指标。以下是数据集在评估流程中的典型使用方式：\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 使用已创建的数据集初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Project_Name\",\n dataset_name=\"MyDataset\"\n)\n\n# 定义与数据集对应的 schema_mapping\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n\n# 添加评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\", \"threshold\": {\"gte\": 0.232323}},\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 在追踪框架中的使用\n\n数据集同样用于追踪框架，用于存储和检索应用运行过程中的追踪记录：\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n```\n\n资料来源：[docs/quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/quickstart.md)\n\n## 最佳实践\n\n1. **命名规范**：数据集名称应具有描述性，便于在项目内识别不同数据集的用途\n2. **模式映射一致性**：确保 schema_mapping 在数据集创建和评估配置中保持一致\n3. **CSV 文件格式**：确保 CSV 文件编码为 UTF-8，且列名与 schema_mapping 的键完全匹配\n4. **先创建后使用**：在进行评估或追踪之前，确保数据集已成功创建并上传\n\n---\n\n\n\n## 评估管理\n\n### 相关页面\n\n相关主题：[数据集管理](#dataset-management), [项目管理](#project-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/evaluation.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/evaluation.py)\n- [ragaai_catalyst/experiment.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/experiment.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [Quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/Quickstart.md)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n \n\n# 评估管理\n\n评估管理是 RagaAI Catalyst 平台的核心功能模块之一，旨在为 RAG（检索增强生成）应用提供标准化的评估框架。该模块允许开发者对 LLM 应用进行系统化评估，通过可配置的评估指标验证应用的实际表现。\n\n## 功能概述\n\n评估管理模块提供以下核心能力：\n\n| 功能 | 描述 |\n|------|------|\n| 评估引擎初始化 | 创建与管理评估实验 |\n| 指标管理 | 添加、配置和查看可用评估指标 |\n| 结果获取 | 获取评估状态与结果数据 |\n| 模式映射 | 支持自定义数据集字段与评估框架的映射 |\n\n## 核心组件\n\n### Evaluation 类\n\n`Evaluation` 类是评估管理的入口点，负责协调整个评估流程。\n\n```python\nfrom ragaai_catalyst import Evaluation\n\nevaluation = Evaluation(\n project_name=\"项目名称\",\n dataset_name=\"数据集名称\"\n)\n```\n\n### 构造函数参数\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| project_name | str | 是 | 项目名称，用于组织和标识评估实验 |\n| dataset_name | str | 是 | 数据集名称，指定用于评估的数据源 |\n\n## 评估工作流程\n\n```mermaid\ngraph TD\n A[初始化评估引擎] --> B[定义模式映射]\n B --> C[添加评估指标]\n C --> D[执行评估]\n D --> E[获取评估状态]\n E --> F{状态检查}\n F -->|完成| G[获取评估结果]\n F -->|进行中| E\n```\n\n## 使用方法\n\n### 基础用法\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Test-RAG-App-1\",\n dataset_name=\"MyDataset\"\n)\n\n# 获取可用指标列表\navailable_metrics = evaluation.list_metrics()\nprint(\"可用指标:\", available_metrics)\n```\n\n### 配置评估指标\n\n定义模式映射，将数据集列映射到评估框架的标准字段：\n\n```python\n# 定义模式映射\nschema_mapping = {\n 'Query': 'prompt', # 用户查询字段\n 'response': 'response', # 模型响应字段\n 'Context': 'context', # 上下文/检索结果字段\n 'expectedResponse': 'expected_response' # 期望响应字段\n}\n\n# 添加评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.5}\n },\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n },\n {\n \"name\": \"AnswerRelevancy\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.7}\n },\n \"column_name\": \"Relevancy_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n### 指标配置参数说明\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| name | str | 指标名称（如 Faithfulness、AnswerRelevancy） |\n| config | dict | 指标配置，包含模型、提供商和阈值设置 |\n| config.model | str | 用于评估的 LLM 模型 |\n| config.provider | str | 模型提供商（如 openai、anthropic） |\n| config.threshold | dict | 阈值条件，支持 gte（大于等于）、lte（小于等于）等操作符 |\n| column_name | str | 结果列名，用于标识评估结果 |\n| schema_mapping | dict | 数据集字段映射配置 |\n\n### 获取评估结果\n\n```python\n# 获取评估状态\nstatus = evaluation.get_status()\nprint(f\"评估状态: {status}\")\n\n# 获取评估结果\nresults = evaluation.get_results()\nprint(f\"评估结果: {results}\")\n```\n\n## 模式映射配置\n\n模式映射是连接数据集与评估框架的关键配置，用于指定数据集中各字段的语义角色。\n\n### 标准字段映射\n\n| 框架字段 | 描述 | 示例数据列名 |\n|----------|------|--------------|\n| Query | 用户输入/问题 | prompt, question, input |\n| response | LLM 生成的回答 | response, answer, output |\n| Context | 检索到的上下文内容 | context, retrieved_docs |\n| expectedResponse | 参考标准答案 | expected_response, ground_truth |\n\n### 自定义映射示例\n\n```python\nschema_mapping = {\n 'Query': 'user_question',\n 'response': 'assistant_reply',\n 'Context': 'retrieved_content',\n 'expectedResponse': 'correct_answer'\n}\n\nevaluation.add_metrics(\n metrics=[{\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\"},\n \"column_name\": \"faithfulness_score\",\n \"schema_mapping\": schema_mapping\n }]\n)\n```\n\n## 支持的评估指标\n\n根据代码结构，评估框架支持多种内置指标，开发者可以通过 `list_metrics()` 方法获取完整的指标列表。\n\n### 常用指标类型\n\n| 指标名称 | 用途 | 阈值示例 |\n|----------|------|----------|\n| Faithfulness | 评估回答对上下文的忠实度 | {\"gte\": 0.5} |\n| AnswerRelevancy | 评估回答与问题的相关性 | {\"gte\": 0.7} |\n| ContextPrecision | 评估检索上下文的精确度 | {\"gte\": 0.6} |\n| ContextRecall | 评估检索上下文的召回率 | {\"gte\": 0.8} |\n\n## 完整使用示例\n\n```python\nfrom ragaai_catalyst import Evaluation\n\n# 1. 初始化评估引擎\nevaluation = Evaluation(\n project_name=\"Product-RAG-Project\",\n dataset_name=\"Product-QA-Dataset\"\n)\n\n# 2. 查看可用指标\nprint(\"可用评估指标:\")\nprint(evaluation.list_metrics())\n\n# 3. 配置模式映射\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'llm_response',\n 'Context': 'retrieved_context',\n 'expectedResponse': 'ground_truth'\n}\n\n# 4. 添加多个评估指标\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.5}\n },\n \"column_name\": \"faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n },\n {\n \"name\": \"AnswerRelevancy\",\n \"config\": {\n \"model\": \"gpt-4o-mini\",\n \"provider\": \"openai\",\n \"threshold\": {\"gte\": 0.7}\n },\n \"column_name\": \"relevancy_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n\n# 5. 检查评估状态\nprint(f\"状态: {evaluation.get_status()}\")\n\n# 6. 获取评估结果\nprint(f\"结果: {evaluation.get_results()}\")\n```\n\n## 集成注意事项\n\n### 前置条件\n\n- 已创建项目并配置有效的认证凭证\n- 已上传包含必要字段的数据集\n- 确保数据集字段与模式映射配置匹配\n\n### 数据集要求\n\n评估数据集应包含以下字段：\n\n1. **prompt** - 用户查询文本\n2. **response** - LLM 生成的回答\n3. **context** - 相关的上下文或检索结果\n4. **expected_response** - 预期的正确答案（可选）\n\n### 错误处理\n\n```python\ntry:\n evaluation = Evaluation(\n project_name=\"NonExistentProject\",\n dataset_name=\"TestDataset\"\n )\n evaluation.add_metrics(metrics=[...])\nexcept Exception as e:\n print(f\"评估初始化失败: {e}\")\n```\n\n## 与其他模块的协作\n\n评估管理模块与其他 RagaAI Catalyst 组件的关系：\n\n```mermaid\ngraph LR\n A[项目] --> B[数据集]\n B --> C[评估管理]\n C --> D[评估指标]\n D --> E[评估结果]\n \n F[追踪管理] --> C\n G[提示词管理] --> C\n```\n\n评估结果可与追踪管理模块结合使用，实现端到端的 LLM 应用监控与优化。\n\n---\n\n\n\n## 提示词管理\n\n### 相关页面\n\n相关主题：[项目管理](#project-management), [合成数据生成](#synthetic-data)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [docs/prompt_management.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/prompt_management.md)\n- [ragaai_catalyst/prompt_manager.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/prompt_manager.py)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n \n\n# 提示词管理\n\n## 概述\n\n提示词管理（Prompt Management）是 RagaAI Catalyst 平台的核心功能模块之一，旨在帮助开发者高效地管理、存储、版本控制和编译提示词模板。该模块提供了统一的接口，使开发者能够在项目中灵活地使用提示词，并支持变量插值、版本管理和动态编译等功能。\n\n提示词管理的核心价值在于将提示词从业务代码中分离出来，实现提示词的集中管理和复用，从而提升应用程序的可维护性和灵活性。开发者可以通过 `PromptManager` 类与平台进行交互，完成提示词的查询、获取和编译等操作。\n\n## 核心组件\n\n### PromptManager 类\n\n`PromptManager` 是提示词管理的入口类，提供了完整的提示词生命周期管理功能。\n\n```python\nfrom ragaai_catalyst import PromptManager\n\n# 初始化 PromptManager\nprompt_manager = PromptManager(project_name=\"Test-RAG-App-1\")\n```\n\n**初始化参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| project_name | str | 是 | 项目名称，用于关联提示词所属的项目 |\n| dataset_name | str | 否 | 数据集名称，可用于特定场景的提示词管理 |\n\n资料来源：[README.md:1-15]()\n\n### Prompt 对象\n\n`Prompt` 对象代表一个具体的提示词模板，包含以下核心方法：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `get_variables()` | dict | 获取提示词中定义的变量列表 |\n| `get_prompt_content()` | str | 获取提示词的原始内容 |\n| `compile(**kwargs)` | dict | 使用指定变量编译提示词 |\n\n资料来源：[README.md:20-35]()\n\n## 功能特性\n\n### 列表查询功能\n\n#### 列出可用提示词\n\n通过 `list_prompts()` 方法可以获取项目下所有可用的提示词模板：\n\n```python\n# 列出所有可用提示词\nprompts = prompt_manager.list_prompts()\nprint(\"Available prompts:\", prompts)\n```\n\n该方法返回提示词名称列表，开发者可以根据实际需求选择合适的提示词进行使用。\n\n#### 获取特定提示词\n\n根据提示词名称获取提示词对象，支持获取最新版本或指定版本：\n\n```python\n# 获取默认版本提示词\nprompt = prompt_manager.get_prompt(prompt_name)\n\n# 获取指定版本提示词\nprompt = prompt_manager.get_prompt(prompt_name, version=\"v1\")\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt_name | str | 是 | 提示词名称 |\n| version | str | 否 | 提示词版本号，默认为最新版本 |\n\n资料来源：[README.md:15-25]()\n\n### 变量提取功能\n\n提示词通常包含动态变量，开发者可以通过 `get_variables()` 方法提取这些变量：\n\n```python\n# 获取提示词中的变量\nvariable = prompt.get_variables()\nprint(\"variable:\", variable)\n```\n\n该方法返回一个字典，包含提示词中定义的所有变量名称及其默认值（如果有）。\n\n### 提示词内容获取\n\n获取提示词的原始模板内容：\n\n```python\n# 获取提示词原始内容\nprompt_content = prompt.get_prompt_content()\nprint(\"prompt_content:\", prompt_content)\n```\n\n返回的 `prompt_content` 是模板字符串，其中包含变量占位符，通常使用 `{{variable_name}}` 或 `{variable_name}` 格式。\n\n### 提示词编译\n\n#### 基本编译\n\n使用 `compile()` 方法将变量值注入到提示词模板中：\n\n```python\n# 编译提示词\ncompiled_prompt = prompt.compile(\n query=\"What's the weather?\",\n context=\"sunny\",\n llm_response=\"It's sunny today\"\n)\nprint(\"Compiled prompt:\", compiled_prompt)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| **kwargs | Any | 是 | 提示词模板中定义的变量及其对应值 |\n\n#### 编译结果使用\n\n编译后的提示词可以直接用于 LLM 调用：\n\n```python\nimport openai\n\ndef get_openai_response(prompt):\n client = openai.OpenAI()\n response = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=prompt\n )\n return response.choices[0].message.content\n\n# 使用编译后的提示词获取响应\nresult = get_openai_response(compiled_prompt)\n```\n\n资料来源：[README.md:30-55]()\n\n## 工作流程\n\n### 标准使用流程\n\n```mermaid\ngraph TD\n A[初始化 PromptManager] --> B[列出可用提示词]\n B --> C[选择提示词名称]\n C --> D[获取提示词对象]\n D --> E[提取变量列表]\n E --> F[准备变量值]\n F --> G[编译提示词]\n G --> H[集成到 LLM 调用]\n H --> I[获取响应结果]\n```\n\n### 版本管理流程\n\n```mermaid\ngraph TD\n A[获取提示词] --> B{指定版本?}\n B -->|是| C[传入 version 参数]\n B -->|否| D[获取最新版本]\n C --> E[验证版本有效性]\n D --> E\n E --> F{版本存在?}\n F -->|是| G[返回提示词对象]\n F -->|否| H[抛出异常]\n```\n\n## 应用场景\n\n### 问答系统\n\n在问答系统中，提示词管理可以用于：\n\n- 管理不同类型的问答模板\n- 支持上下文注入\n- 处理多轮对话场景\n\n### RAG 应用\n\n在检索增强生成（RAG）应用中，提示词管理发挥着重要作用：\n\n- 管理检索上下文模板\n- 处理多文档场景\n- 支持自定义生成风格\n\n### Agent 应用\n\n对于 Agent 应用，提示词管理支持：\n\n- 工具调用指令模板\n- 系统提示词管理\n- 角色定义模板\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-80]()\n\n## 配置与集成\n\n### 环境配置\n\n提示词管理功能需要与 RagaAICatalyst 配合使用，需要配置以下凭证：\n\n```python\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\n# 从环境变量或配置文件获取凭证\naccess_key = os.getenv('RAGAAI_CATALYST_ACCESS_KEY')\nsecret_key = os.getenv('RAGAAI_CATALYST_SECRET_KEY')\nbase_url = os.getenv('RAGAAI_CATALYST_BASE_URL')\nproject_name = os.getenv('RAGAAI_PROJECT_NAME')\n```\n\n### 与追踪系统集成\n\n提示词管理可以与 RagaAI 的追踪系统无缝集成：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化催化剂实例\ncatalyst = RagaAICatalyst(\n access_key=access_key,\n secret_key=secret_key,\n base_url=base_url\n)\n\n# 初始化追踪器\ntracer = Tracer(\n project_name=project_name,\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"agentic/langchain\"\n)\n\n# 启用自动追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/langchain/medical_rag/diagnosis_agent.py:1-35]()\n\n## 最佳实践\n\n### 提示词设计原则\n\n1. **变量命名清晰**：使用描述性的变量名称，便于理解和使用\n2. **版本控制**：为重要提示词添加版本号，便于追踪变更\n3. **模块化设计**：将复杂提示词拆分为可复用的模块\n4. **文档完善**：为提示词添加说明和示例\n\n### 性能优化\n\n1. **缓存提示词对象**：避免重复获取相同的提示词\n2. **批量编译**：对于大量相似请求，考虑批量处理\n3. **异步调用**：在需要时使用异步方式获取提示词\n\n### 安全考虑\n\n1. **敏感信息处理**：避免在提示词中硬编码敏感信息\n2. **访问控制**：确保只有授权用户可以修改提示词\n3. **审计日志**：记录提示词的访问和修改历史\n\n## 相关模块\n\n| 模块名称 | 功能说明 |\n|----------|----------|\n| RagaAICatalyst | 核心催化剂类，提供认证和基础服务 |\n| Tracer | 追踪模块，用于监控应用行为 |\n| Dataset | 数据集管理，与提示词配合使用 |\n| Evaluation | 评估模块，用于验证提示词效果 |\n| RedTeaming | 红队测试，评估提示词安全性 |\n\n## 常见问题\n\n### Q: 如何处理提示词版本冲突？\n\n**A:** 建议在获取提示词时明确指定版本号，避免因默认版本更新导致的行为差异。\n\n### Q: 提示词编译失败怎么办？\n\n**A:** 首先检查变量名称是否与模板定义一致，其次确认所有必填变量都已提供。\n\n### Q: 如何管理大量提示词？\n\n**A:** 建议按功能模块或应用场景对提示词进行分组，使用规范化的命名约定便于检索。\n\n## 总结\n\n提示词管理是 RagaAI Catalyst 平台的重要功能，通过提供统一的接口和完善的管理机制，帮助开发者更高效地管理和使用提示词模板。该模块支持版本控制、变量提取、动态编译等核心功能，可以广泛应用于问答系统、RAG 应用和 Agent 应用等多种场景。与平台的追踪、评估等模块配合使用，能够构建完整的 AI 应用开发工作流。\n\n---\n\n\n\n## 智能体追踪系统\n\n### 相关页面\n\n相关主题：[追踪器类型与框架支持](#tracer-types), [配置与认证](#configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/tracers/tracer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n- [ragaai_catalyst/tracers/agentic_tracing/__init__.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/__init__.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/all_llm_provider/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n- [docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n \n\n# 智能体追踪系统\n\n## 概述\n\n智能体追踪系统（Agentic Tracing System）是 RagaAI Catalyst 平台的核心组件之一，旨在为基于大语言模型的智能体应用提供全面的可观测性解决方案。该系统通过自动插桩和自定义追踪两种模式，捕获智能体执行过程中的关键信息，包括 LLM 调用、工具执行、代理行为、用户交互、文件操作和网络通信等各个环节。\n\n智能体追踪系统支持多种主流 AI 框架的深度集成，包括 LangGraph、LangChain、CrewAI、SmolaAgents、OpenAI Agents 和 LlamaIndex 等。系统将这些框架的执行轨迹统一标准化后上传至 RagaAI 云端平台，便于开发者进行性能分析、调试和优化。\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n## 架构设计\n\n### 整体架构\n\n智能体追踪系统采用分层架构设计，从底层到顶层依次包括数据采集层、标准化处理层和上传服务层。各层之间通过事件驱动的方式进行通信，确保追踪数据的完整性和时效性。\n\n```mermaid\ngraph TD\n A[应用层] --> B[自动插桩层]\n A --> C[手动追踪层]\n B --> D[事件收集器]\n C --> D\n D --> E[数据标准化处理器]\n E --> F[轨迹导出器]\n F --> G[RagaAI 云端平台]\n \n B -.-> H[LLM 插桩]\n B -.-> I[工具插桩]\n B -.-> J[代理插桩]\n B -.-> K[用户交互插桩]\n B -.-> L[文件IO插桩]\n B -.-> M[网络插桩]\n B -.-> N[自定义插桩]\n```\n\n### 核心组件\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| Tracer | 主入口类，负责初始化和配置追踪器 | ragaai_catalyst/tracers/tracer.py |\n| AgenticTracing | 核心追踪逻辑基类 | ragaai_catalyst/tracers/agentic_tracing/__init__.py |\n| AgenticTracer | 基于 OpenInference 的追踪实现 | ragaai_catalyst/tracers/agentic_tracing/tracers/base.py |\n| RAGATraceExporter | 轨迹数据导出器 | ragaai_catalyst/tracers/exporters/ragaai_trace_exporter.py |\n| SystemMonitor | 系统资源监控模块 | ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py |\n| LLMTracerMixin | LLM 调用追踪混入类 | ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:1-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 支持的追踪器类型\n\n智能体追踪系统通过 `tracer_type` 参数区分不同的追踪目标。系统支持两大类追踪模式：**智能体类追踪器**和**RAG 类追踪器**。\n\n### 智能体类追踪器\n\n| tracer_type 参数值 | 支持框架 | 依赖包 |\n|------------------|---------|--------|\n| `agentic/langgraph` | LangGraph | langgraph |\n| `agentic/langchain` | LangChain | langchain-community |\n| `agentic/crewai` | CrewAI | crewai |\n| `agentic/smolagents` | SmolaAgents | smolagents |\n| `agentic/openai_agents` | OpenAI Agents SDK | openai |\n| `agentic/llamaindex` | LlamaIndex | llamaindex |\n| `agentic/haystack` | Haystack | haystack-ai |\n\n资料来源：[ragaai_catalyst/tracer.py:60-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### RAG 类追踪器\n\n| tracer_type 参数值 | 支持框架 | 依赖包 |\n|------------------|---------|--------|\n| `rag/langchain` | LangChain RAG 应用 | langchain-community |\n\n### 通用智能体追踪器\n\n当 `tracer_type` 设置为 `agentic`（不含具体框架后缀）时，系统将启用通用智能体追踪模式，同时支持 VertexAI、Anthropic、LiteLLM、OpenAI 等多个 LLM 提供商的插桩。\n\n资料来源：[ragaai_catalyst/tracer.py:80-150](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 快速入门\n\n### 环境配置\n\n在使用智能体追踪系统之前，需要确保已完成以下配置：\n\n```bash\npip install ragaai-catalyst\n```\n\n并设置环境变量或在代码中初始化认证信息：\n\n```python\nimport os\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n资料来源：[examples/all_llm_provider/config.py:1-20](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/all_llm_provider/config.py)\n\n### 自动插桩模式\n\n自动插桩是智能体追踪系统最便捷的使用方式。只需初始化追踪器并调用 `init_tracing` 函数，系统即可自动捕获应用中的各类操作。\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化 RagaAI Catalyst\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/langgraph\" # 根据实际框架选择\n)\n\n# 启用自动插桩\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n### 自定义追踪模式\n\n对于需要精确控制追踪范围和时机的场景，系统提供两种自定义追踪方式：\n\n#### 方式一：上下文管理器方式\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"tracer_dataset_name\",\n tracer_type=\"agentic/langgraph\"\n)\n\nwith tracer():\n # 需要追踪的代码块\n result = your_agent.run(\"用户输入\")\n```\n\n#### 方式二：手动启停方式\n\n```python\ntracer.start()\n\n# 需要追踪的代码\nresult = your_agent.run(\"用户输入\")\n\ntracer.stop()\n\n# 验证数据上传状态\nprint(tracer.get_upload_status())\n```\n\n资料来源：[docs/agentic_tracing.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/docs/agentic_tracing.md)\n\n## Tracer 类详解\n\n### 构造函数参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| project_name | str | 必需 | RagaAI 项目名称 |\n| dataset_name | str | 必需 | 数据集名称 |\n| trace_name | str | None | 自定义轨迹名称 |\n| tracer_type | str | None | 追踪器类型 |\n| pipeline | object | None | 管道对象 |\n| metadata | dict | None | 自定义元数据 |\n| description | str | None | 追踪描述 |\n| timeout | int | 120 | 上传超时时间（秒） |\n| update_llm_cost | bool | True | 是否更新 LLM 成本 |\n| auto_instrumentation | dict | 见下方 | 自动插桩配置 |\n| interval_time | int | 2 | 上传间隔时间（秒） |\n| max_upload_workers | int | 30 | 最大上传线程数 |\n| external_id | str | None | 外部标识符 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:30-70](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### 自动插桩配置\n\n`auto_instrumentation` 参数用于精细控制自动插桩的范围，默认配置如下：\n\n```python\nauto_instrumentation = {\n 'llm': True, # LLM 调用追踪\n 'tool': True, # 工具执行追踪\n 'agent': True, # 代理行为追踪\n 'user_interaction': True, # 用户交互追踪\n 'file_io': True, # 文件操作追踪\n 'network': True, # 网络请求追踪\n 'custom': True # 自定义事件追踪\n}\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:40-50](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n### 模型成本配置\n\n系统支持设置自定义模型成本，用于追踪 LLM 调用费用：\n\n```python\ntracer.set_model_cost({\n \"model_name\": \"gpt-4\",\n \"input_cost_per_million_token\": 6,\n \"output_cost_per_million_token\": 2.40\n})\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:100-130](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n\n## 与各框架的集成\n\n### CrewAI 集成\n\nCrewAI 是多智能体协作框架，RagaAI Catalyst 提供原生的 CrewAI 追踪支持：\n\n```python\nfrom crewai import Agent, Task, Crew, Process\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\n# 初始化追踪\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\",\n)\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 创建 CrewAI 应用\nbrainstormer = Agent(\n role=\"创意生成器\",\n goal=\"生成创意性想法\",\n backstory=\"你是一位富有想象力的思考者\"\n)\n\ncrew = Crew(\n agents=[brainstormer],\n tasks=[brainstorm_task],\n process=Process.sequential\n)\n\nresult = crew.kickoff()\n```\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:1-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n\n### SmolaAgents 集成\n\nSmolaAgents 是轻量级智能体框架，适用于简单到中等复杂度的任务：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/smolagents\",\n)\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/smolagents/most_upvoted_paper/README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/smolagents/most_upvoted_paper/README.md)\n\n### 自定义代理集成\n\n对于自定义代理应用，系统提供通用的智能体追踪支持：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ndef initialize_tracing():\n catalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n )\n\n tracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\", # 通用智能体模式\n )\n\n init_tracing(catalyst=catalyst, tracer=tracer)\n return tracer\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:1-30](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n\n## 工作流程\n\n智能体追踪系统的工作流程可划分为以下四个阶段：\n\n```mermaid\ngraph LR\n A[初始化] --> B[配置追踪器]\n B --> C[自动插桩/手动追踪]\n C --> D[数据收集]\n D --> E[数据标准化]\n E --> F[上传至云端]\n F --> G[查看分析结果]\n```\n\n### 阶段一：初始化\n\n在应用启动时，首先创建 `RagaAICatalyst` 实例和 `Tracer` 实例，建立与 RagaAI 平台的连接。\n\n### 阶段二：配置追踪器\n\n根据实际使用的框架选择合适的 `tracer_type`，并通过 `init_tracing` 函数启用自动插桩功能。\n\n### 阶段三：执行追踪\n\n应用运行时，追踪器自动捕获各类操作事件。对于需要特定追踪范围的场景，可使用上下文管理器或手动启停方式。\n\n### 阶段四：数据上传\n\n追踪数据经过标准化处理后，通过后台任务异步上传至 RagaAI 云端平台。用户可通过 `get_upload_status()` 方法查看上传状态。\n\n## 系统资源监控\n\n智能体追踪系统集成了系统资源监控功能，用于记录追踪期间的系统环境信息：\n\n| 监控项 | 说明 |\n|-------|------|\n| CPU | 处理器型号、核心数、线程数 |\n| 内存 | 总内存、可用内存 |\n| 磁盘 | 总容量、可用空间 |\n| 网络 | 上传/下载速度 |\n| Python 环境 | Python 版本、已安装包列表 |\n\n资料来源：[ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py:20-80](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py)\n\n## 最佳实践\n\n### 选择合适的追踪模式\n\n| 场景 | 推荐模式 |\n|-----|---------|\n| 快速集成，追踪全部操作 | 自动插桩模式 |\n| 精确控制追踪范围 | 上下文管理器模式 |\n| 长时间运行的后台任务 | 手动启停模式 |\n\n### 性能考虑\n\n- 默认上传间隔为 2 秒，可通过 `interval_time` 参数调整\n- 最大上传线程数为 30，可通过 `max_upload_workers` 参数调整\n- 对于高频调用场景，建议适当增大 `interval_time` 以减少网络开销\n\n### 安全性建议\n\n- 妥善保管 `access_key` 和 `secret_key`，避免硬编码在代码中\n- 推荐使用环境变量或配置中心管理敏感信息\n- 定期轮换认证凭证\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 追踪数据未上传 | 网络连接问题 | 检查网络配置和 `base_url` |\n| 框架未被识别 | `tracer_type` 配置错误 | 确认使用正确的追踪器类型 |\n| 数据不完整 | 插桩范围限制 | 检查 `auto_instrumentation` 配置 |\n| 上传超时 | `timeout` 过小 | 增大 `timeout` 参数值 |\n\n### 调试模式\n\n启用调试模式以获取详细日志：\n\n```python\nimport os\nos.environ[\"DEBUG\"] = \"1\"\n```\n\n设置后，追踪器将输出详细的调试信息，便于定位问题。\n\n## 总结\n\n智能体追踪系统是 RagaAI Catalyst 平台的核心功能之一，通过统一的标准化的追踪机制，为开发者提供跨框架的可观测性解决方案。该系统支持灵活的自动插桩和自定义追踪两种模式，兼容多种主流 AI 框架，并提供完整的资源监控和数据分析能力。无论是快速原型开发还是生产环境监控，智能体追踪系统都能提供有力的技术支持。\n\n---\n\n\n\n## 追踪器类型与框架支持\n\n### 相关页面\n\n相关主题：[智能体追踪系统](#agentic-tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/tracers/tracer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/tracers/tracer.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n \n\n# 追踪器类型与框架支持\n\n## 概述\n\nRagaAI Catalyst 的追踪器（Tracer）系统为各种 AI 代理和 LLM 框架提供统一的追踪和监控能力。通过支持多种主流框架，开发者可以在不同的技术栈中实现一致的追踪体验。\n\n追踪器类型的核心作用是根据不同的框架自动配置相应的检测器（Instrumentors），并通过统一的接口管理追踪生命周期，包括启动、停止和上传追踪数据。\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:1-50]()\n\n## 支持的追踪器类型\n\n### 追踪器类型总览\n\nRagaAI Catalyst 支持以下追踪器类型：\n\n| 追踪器类型 | 框架 | 说明 |\n|-----------|------|------|\n| `agentic/langgraph` | LangGraph | 图结构代理框架追踪 |\n| `agentic/langchain` | LangChain | 通用 LangChain 追踪 |\n| `agentic/llamaindex` | LlamaIndex | LlamaIndex 代理追踪 |\n| `agentic/smolagents` | SmolAgents | 轻量级代理框架追踪 |\n| `agentic/openai_agents` | OpenAI Agents | OpenAI 官方代理 SDK |\n| `agentic/haystack` | Haystack | Haystack AI 框架追踪 |\n| `agentic/crewai` | CrewAI | 多代理协作框架追踪 |\n| `agentic/autogen` | AutoGen | 微软 AutoGen 多代理框架 |\n| `rag/langchain` | LangChain (RAG) | LangChain RAG 专用追踪 |\n| `langchain` | LangChain | 传统 LangChain 追踪 |\n| `llamaindex` | LlamaIndex | 传统 LlamaIndex 追踪 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:45-90]()\n\n## 框架支持架构\n\n### 架构层次\n\n```mermaid\ngraph TD\n A[Tracer 追踪器主类] --> B[AgenticTracing 基础类]\n B --> C[框架特定检测器]\n \n C --> D[LLM 检测器]\n C --> E[Tool 检测器]\n C --> F[Agent 检测器]\n C --> G[User Interaction 检测器]\n \n D --> D1[LiteLLMInstrumentor]\n D --> D2[OpenAIInstrumentor]\n D --> D3[AnthropicInstrumentor]\n D --> D4[GroqInstrumentor]\n D --> D5[VertexAIInstrumentor]\n \n E --> E1[Tool Callbacks]\n F --> F1[Agent Callbacks]\n G --> G1[User Interaction Callbacks]\n \n H[RAGATraceExporter] --> I[追踪数据上传]\n```\n\n### 追踪器初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Tracer as Tracer 类\n participant Setup as 框架设置\n participant Instrumentor as 检测器\n \n User->>Tracer: 初始化 Tracer(tracer_type)\n Tracer->>Tracer: 验证 tracer_type\n Tracer->>Setup: 调用框架特定设置\n Setup->>Instrumentor: 加载对应 Instrumentors\n Instrumentor-->>Setup: 返回检测器实例\n Setup-->>Tracer: 完成配置\n Tracer-->>User: 返回 Tracer 实例\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:60-120]()\n\n## 追踪器核心参数\n\n### Tracer 类初始化参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `project_name` | str | 必需 | 项目名称 |\n| `dataset_name` | str | 必需 | 数据集名称 |\n| `tracer_type` | str | None | 追踪器类型 |\n| `trace_name` | str | None | 追踪名称 |\n| `pipeline` | object | None | 管道对象 |\n| `metadata` | dict | None | 元数据 |\n| `description` | str | None | 描述信息 |\n| `timeout` | int | 120 | 超时时间（秒） |\n| `update_llm_cost` | bool | True | 是否更新模型成本 |\n| `auto_instrumentation` | dict | 见下文 | 自动检测配置 |\n| `interval_time` | int | 2 | 间隔时间（秒） |\n| `max_upload_workers` | int | 30 | 最大上传工作线程数 |\n| `external_id` | str | None | 外部 ID |\n\n### auto_instrumentation 配置\n\n`auto_instrumentation` 参数控制自动检测的组件类型：\n\n| 键 | 类型 | 默认值 | 说明 |\n|----|------|--------|------|\n| `llm` | bool | True | LLM 调用追踪 |\n| `tool` | bool | True | 工具调用追踪 |\n| `agent` | bool | True | 代理行为追踪 |\n| `user_interaction` | bool | True | 用户交互追踪 |\n| `file_io` | bool | True | 文件 IO 追踪 |\n| `network` | bool | True | 网络请求追踪 |\n| `custom` | bool | True | 自定义追踪 |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:30-45]()\n\n## 框架集成示例\n\n### LangGraph 框架集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n\ntracer = Tracer(\n project_name=\"my-project\",\n dataset_name=\"my-dataset\",\n tracer_type=\"agentic/langgraph\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/langgraph/personal_research_assistant/research_assistant.py:20-35]()\n\n### CrewAI 框架集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),\n secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),\n base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')\n)\n\ntracer = Tracer(\n project_name=os.getenv('RAGAAI_PROJECT_NAME'),\n dataset_name=os.getenv('RAGAAI_DATASET_NAME'),\n tracer_type=\"agentic/crewai\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/crewai/scifi_writer/scifi_writer.py:10-25]()\n\n### SmolAgents 框架集成\n\nSmolAgents 框架通过 `SmolagentsInstrumentor` 进行检测：\n\n```python\ntracer = Tracer(\n project_name=\"project_name\",\n dataset_name=\"dataset_name\",\n tracer_type=\"agentic/smolagents\"\n)\n```\n\n### 自定义代理集成\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing\nfrom ragaai_catalyst.tracers import Tracer\n\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\")\n)\n\ntracer = Tracer(\n project_name=os.getenv(\"RAGAAI_PROJECT_NAME\"),\n dataset_name=os.getenv(\"RAGAAI_DATASET_NAME\"),\n tracer_type=\"Agentic\" # 通用代理追踪\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:10-25]()\n\n## LLM 检测器支持\n\nRagaAI Catalyst 支持多种 LLM 提供商的检测：\n\n| 提供商 | 检测器类 | 说明 |\n|--------|----------|------|\n| OpenAI | `OpenAIInstrumentor` | OpenAI GPT 系列 |\n| Anthropic | `AnthropicInstrumentor` | Claude 系列 |\n| Google VertexAI | `VertexAIInstrumentor` | Google Gemini 等 |\n| Groq | `GroqInstrumentor` | Groq LPU |\n| LiteLLM | `LiteLLMInstrumentor` | 统一 LLM 接口 |\n\n检测器自动根据 `tracer_type` 进行加载：\n\n```python\nif tracer_type in ['agentic/crewai']:\n from openinference.instrumentation.vertexai import VertexAIInstrumentor\n instrumentors.append((VertexAIInstrumentor, []))\n from openinference.instrumentation.anthropic import AnthropicInstrumentor\n instrumentors.append((AnthropicInstrumentor, []))\n from openinference.instrumentation.groq import GroqInstrumentor\n instrumentors.append((GroqInstrumentor, []))\n from openinference.instrumentation.litellm import LiteLLMInstrumentor\n instrumentors.append((LiteLLMInstrumentor, []))\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:65-85]()\n\n## 追踪生命周期管理\n\n### 追踪启动和停止\n\nRagaAI Catalyst 提供两种追踪控制方式：\n\n#### 方式一：上下文管理器\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\nwith tracer():\n # 您的代码逻辑\n pass\n```\n\n#### 方式二：手动控制\n\n```python\nfrom ragaai_catalyst import Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\ntracer.start()\n# 您的代码逻辑\ntracer.stop()\n\n# 验证上传状态\nprint(tracer.get_upload_status())\n```\n\n资料来源：[quickstart.md](quickstart.md)\n\n### 不同框架的启动行为\n\n| 追踪器类型 | 启动方式 | 特殊处理 |\n|-----------|----------|----------|\n| `langchain` | `super().start()` | 直接调用父类 |\n| `llamaindex` | `LlamaIndexInstrumentationTracer` | 自定义转换器 |\n| `rag/langchain` | `super().start()` | RAG 专用处理 |\n| 其他 agentic 类型 | `super().start()` | 统一处理 |\n\n```python\ndef start(self):\n if self.tracer_type == \"langchain\":\n super().start()\n return self\n elif self.tracer_type == \"llamaindex\":\n self.llamaindex_tracer = LlamaIndexInstrumentationTracer(self._pass_user_data())\n return self.llamaindex_tracer.start()\n else:\n super().start()\n return self\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:180-195]()\n\n## 自动检测与手动检测\n\n### 自动检测（Auto-Instrumentation）\n\n自动检测在初始化时启用，可通过 `init_tracing` 函数配置：\n\n```python\nfrom ragaai_catalyst import init_tracing, Tracer\n\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\"\n)\n\ninit_tracing(catalyst=catalyst, tracer=tracer)\n```\n\n### 自动检测组件控制\n\n可通过 `auto_instrumentation` 参数精细控制：\n\n```python\ntracer = Tracer(\n project_name=\"Project_Name\",\n dataset_name=\"Dataset_Name\",\n tracer_type=\"agentic/langgraph\",\n auto_instrumentation={\n 'llm': True, # 启用 LLM 追踪\n 'tool': True, # 启用工具追踪\n 'agent': True, # 启用代理追踪\n 'user_interaction': True, # 启用用户交互追踪\n 'file_io': True, # 启用文件 IO 追踪\n 'network': True, # 启用网络请求追踪\n 'custom': True # 启用自定义追踪\n }\n)\n```\n\n### 框架特定检测器\n\n| 框架 | 检测器类 | 导入路径 |\n|------|----------|----------|\n| LangGraph | `LangGraphInstrumentor` | `openinference.instrumentation.langgraph` |\n| LangChain | `LangChainInstrumentor` | `openinference.instrumentation.langchain` |\n| SmolAgents | `SmolagentsInstrumentor` | `openinference.instrumentation.smolagents` |\n| OpenAI Agents | `OpenAIAgentsInstrumentor` | `openinference.instrumentation.openai_agents` |\n| AutoGen | `AutogenInstrumentor` | `openinference.instrumentation.autogen` |\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:90-115]()\n\n## 模型成本追踪\n\n### 设置自定义模型成本\n\nRagaAI Catalyst 支持追踪 LLM 调用成本：\n\n```python\ntracer.set_model_cost({\n \"model_name\": \"gpt-4\",\n \"input_cost_per_million_token\": 6,\n \"output_cost_per_million_token\": 2.40\n})\n```\n\n### 成本追踪参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model_name` | str | 模型名称 |\n| `input_cost_per_million_token` | float | 每百万输入 token 成本 |\n| `output_cost_per_million_token` | float | 每百万输出 token 成本 |\n\n可通过 `update_llm_cost=False` 禁用成本更新：\n\n```python\ntracer = Tracer(\n project_name=\"project\",\n dataset_name=\"dataset\",\n tracer_type=\"agentic/langgraph\",\n update_llm_cost=False\n)\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:125-145]()\n\n## 快速参考\n\n### 追踪器类型选择指南\n\n| 应用场景 | 推荐追踪器类型 |\n|----------|----------------|\n| LangGraph 工作流 | `agentic/langgraph` |\n| LangChain 链式调用 | `agentic/langchain` 或 `langchain` |\n| LlamaIndex 查询引擎 | `agentic/llamaindex` |\n| SmolAgents 代理 | `agentic/smolagents` |\n| CrewAI 多代理系统 | `agentic/crewai` |\n| RAG 应用（LangChain） | `rag/langchain` |\n| 通用代理应用 | `Agentic` 或 `agentic` |\n| AutoGen 多代理 | `agentic/autogen` |\n\n### 最小配置示例\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst, init_tracing, Tracer\n\n# 初始化 Catalyst\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\"\n)\n\n# 创建追踪器\ntracer = Tracer(\n project_name=\"my-project\",\n dataset_name=\"my-dataset\",\n tracer_type=\"agentic/langgraph\"\n)\n\n# 启用追踪\ninit_tracing(catalyst=catalyst, tracer=tracer)\n\n# 使用上下文管理器运行代码\nwith tracer():\n # 您的代理代码\n pass\n```\n\n资料来源：[README.md](README.md)\n\n## 错误处理与调试\n\n### 常见问题处理\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 追踪器未启动 | 未调用 `init_tracing` | 确保在代码前调用 `init_tracing` |\n| 框架未检测到 | tracer_type 不匹配 | 检查框架对应的正确 tracer_type |\n| 上传失败 | 网络或认证问题 | 检查 `get_upload_status()` 返回状态 |\n| LlamaIndex 追踪失败 | 未先调用 `start()` | 确保显式调用 `tracer.start()` |\n\n### 调试模式\n\n启用调试模式查看详细日志：\n\n```bash\nexport DEBUG=1\n```\n\n或在代码中设置日志级别：\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n资料来源：[ragaai_catalyst/tracers/tracer.py:15-20]()\n\n---\n\n\n\n## 合成数据生成\n\n### 相关页面\n\n相关主题：[提示词管理](#prompt-management), [数据集管理](#dataset-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [tests_requirements.txt](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/tests_requirements.txt)\n- [examples/langgraph/personal_research_assistant/research_assistant.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/langgraph/personal_research_assistant/research_assistant.py)\n- [examples/crewai/scifi_writer/scifi_writer.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/crewai/scifi_writer/scifi_writer.py)\n \n\n# 合成数据生成\n\n## 概述\n\n合成数据生成（Synthetic Data Generation）是 RagaAI Catalyst 平台提供的重要功能模块之一。该模块允许用户通过 LLM（大型语言模型）自动生成测试数据集，用于 RAG 应用的质量评估和测试场景构建。\n\n在 RAG（检索增强生成）应用开发过程中，高质量测试数据的获取往往是开发者面临的主要挑战之一。合成数据生成功能通过利用强大的语言模型能力，帮助开发者快速创建多样化的测试用例，从而提升应用的质量和鲁棒性。\n\n## 核心功能特性\n\nRagaAI Catalyst 的合成数据生成模块具有以下核心能力：\n\n| 功能特性 | 描述 |\n|---------|------|\n| 多源数据生成 | 支持基于不同数据源生成合成数据 |\n| Schema 映射 | 提供灵活的数据 Schema 映射机制 |\n| 批量生成 | 支持批量生成测试数据集 |\n| 质量控制 | 内置数据质量验证机制 |\n| 格式支持 | 支持 CSV、JSONL 等多种输出格式 |\n\n## 系统架构\n\n合成数据生成模块在 RagaAI Catalyst 整体架构中扮演着数据准备的关键角色。以下是平台的核心架构图：\n\n```mermaid\ngraph TD\n A[RagaAI Catalyst] --> B[项目管理]\n A --> C[数据集管理]\n A --> D[评估框架]\n A --> E[跟踪系统]\n A --> F[提示词管理]\n A --> G[Guardrail 管理]\n A --> H[红队测试]\n A --> I[合成数据生成]\n \n I --> I1[数据源配置]\n I --> I2[Schema 映射]\n I --> I3[生成引擎]\n I --> I4[质量验证]\n \n C --> C1[CSV 导入]\n C --> C2[DataFrame 导入]\n C --> C3[JSONL 导入]\n```\n\n## 工作流程\n\n合成数据生成的标准工作流程包含以下步骤：\n\n```mermaid\ngraph TD\n A[初始化 RagaAICatalyst] --> B[配置数据集管理器]\n B --> C[定义 Schema 映射]\n C --> D[调用合成数据生成接口]\n D --> E[执行 LLM 生成]\n E --> F[质量验证]\n F --> G{验证通过?}\n G -->|是| H[保存生成的数据]\n G -->|否| I[重新生成或调整参数]\n I --> D\n H --> J[集成到评估流程]\n```\n\n## 使用方法\n\n### 初始化配置\n\n使用合成数据生成功能前，需要完成基础配置：\n\n```python\nfrom ragaai_catalyst import RagaAICatalyst\n\ncatalyst = RagaAICatalyst(\n access_key=\"YOUR_ACCESS_KEY\",\n secret_key=\"YOUR_SECRET_KEY\",\n base_url=\"BASE_URL\"\n)\n```\n\n### 数据集管理集成\n\n合成数据生成与数据集管理模块紧密集成，支持将生成的数据直接导入到项目数据集中：\n\n```python\nfrom ragaai_catalyst import Dataset\n\ndataset_manager = Dataset(project_name=\"Project_Name\")\n\n# 创建数据集\ndataset_manager.create_from_csv(\n csv_path=\"path/to/your.csv\",\n dataset_name=\"SyntheticDataset\",\n schema_mapping={\n 'column1': 'schema_element1',\n 'column2': 'schema_element2'\n }\n)\n```\n\n## 与评估框架的集成\n\n合成数据生成的主要用途之一是为评估框架提供测试数据。评估框架支持多种内置指标：\n\n```python\nfrom ragaai_catalyst import Evaluation\n\nevaluation = Evaluation(\n project_name=\"Project_Name\",\n dataset_name=\"SyntheticDataset\"\n)\n\n# 添加评估指标\nschema_mapping = {\n 'Query': 'prompt',\n 'response': 'response',\n 'Context': 'context',\n 'expectedResponse': 'expected_response'\n}\n\nevaluation.add_metrics(\n metrics=[\n {\n \"name\": \"Faithfulness\",\n \"config\": {\"model\": \"gpt-4o-mini\", \"provider\": \"openai\", \"threshold\": {\"gte\": 0.5}},\n \"column_name\": \"Faithfulness_v1\",\n \"schema_mapping\": schema_mapping\n }\n ]\n)\n```\n\n## 支持的 LLM 提供商\n\n合成数据生成功能支持多种 LLM 提供商，包括：\n\n| 提供商 | 支持状态 | 说明 |\n|-------|---------|------|\n| OpenAI | ✅ 完全支持 | 支持 GPT-4o、GPT-4o-mini 等模型 |\n| Anthropic | ✅ 完全支持 | 支持 Claude 系列模型 |\n| Google Generative AI | ✅ 完全支持 | 支持 Gemini 系列模型 |\n| xAI | ✅ 完全支持 | 支持 Grok 系列模型 |\n| Vertex AI | ✅ 完全支持 | 支持 Google Cloud Vertex AI |\n| Ollama | ✅ 完全支持 | 支持本地部署的模型 |\n\n支持的追踪器类型包括：`agentic/langgraph`、`agentic/langchain`、`agentic/smolagents`、`agentic/openai_agents`、`agentic/llamaindex`、`agentic/haystack` 等。\n\n## 最佳实践\n\n### 1. Schema 设计建议\n\n在设计合成数据的 Schema 时，应注意以下要点：\n\n- 确保字段命名清晰且具有描述性\n- 定义明确的字段类型和数据约束\n- 合理规划必填字段和可选字段\n\n### 2. 数据质量控制\n\n建议在生成合成数据后进行以下质量检查：\n\n- 验证数据的完整性和一致性\n- 检查数据分布的合理性\n- 确保生成的问答对具有逻辑性\n\n### 3. 与真实数据结合\n\n最佳实践建议将合成数据与真实数据结合使用：\n\n- 使用合成数据补充边缘案例\n- 使用真实数据验证合成数据的质量\n- 定期更新合成数据以覆盖新场景\n\n## 相关模块\n\n合成数据生成与其他 RagaAI Catalyst 模块协同工作：\n\n- **数据集管理**：存储和管理生成的合成数据\n- **评估框架**：使用合成数据进行模型评估\n- **提示词管理**：优化数据生成的提示词模板\n- **跟踪系统**：监控数据生成过程的性能\n\n## 总结\n\n合成数据生成是 RagaAI Catalyst 平台中用于自动化测试数据创建的核心功能。通过与多种 LLM 提供商的集成，开发者可以灵活地生成高质量的测试数据集，有效提升 RAG 应用的开发和评估效率。该功能与平台的数据集管理、评估框架等模块紧密集成，为用户提供了一整套完整的数据准备和评估解决方案。\n\n---\n\n\n\n## 安全护栏管理\n\n### 相关页面\n\n相关主题：[评估管理](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ragaai_catalyst/guardrails_manager.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/guardrails_manager.py)\n- [ragaai_catalyst/guard_executor.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/ragaai_catalyst/guard_executor.py)\n- [README.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/README.md)\n- [quickstart.md](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/quickstart.md)\n- [examples/custom_agents/travel_agent/config.py](https://github.com/raga-ai-hub/RagaAI-Catalyst/blob/main/examples/custom_agents/travel_agent/config.py)\n \n\n# 安全护栏管理\n\n## 概述\n\n安全护栏管理（Guardrail Management）是RagaAI Catalyst平台的核心功能模块之一，旨在为AI应用提供实时的输入输出安全检查与过滤机制。该模块通过预定义的检测器和自定义规则，对LLM（大型语言模型）的输入提示词和生成内容进行多维度安全评估，确保AI应用在预设的安全边界内运行。\n\n安全护栏管理的主要职责包括：\n\n- **输入护栏**：在用户输入到达LLM之前进行内容审查和过滤\n- **输出护栏**：对模型生成的回答进行安全合规性检查\n- **策略配置**：支持用户自定义检测规则和响应策略\n- **结果追踪**：记录每次安全检查的执行结果和决策依据\n\n资料来源：[README.md:1-15]()\n\n## 核心组件架构\n\nRagaAI Catalyst的安全护栏系统由两个核心模块组成，它们协同工作以提供完整的安全保护能力。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Guardrails Manager]\n B --> C{检测器选择}\n C --> D[内置检测器]\n C --> E[自定义检测器]\n D --> F[Guard Executor]\n E --> F\n F --> G[安全决策]\n G --> H{通过?}\n H -->|是| I[转发至LLM]\n H -->|否| J[拦截/过滤]\n I --> K[LLM响应]\n K --> L[输出护栏检查]\n L --> M{合规?}\n M -->|是| N[返回用户]\n M -->|否| O[内容过滤]\n J --> P[返回安全响应]\n O --> P\n N --> P\n```\n\n### Guardrails Manager\n\n`GuardrailsManager`是护栏系统的主入口模块，负责护栏实例的创建、配置和管理。该模块提供了统一的API接口，使开发者能够便捷地集成安全护栏功能到现有应用中。\n\n主要功能特性：\n\n- **实例生命周期管理**：创建、配置、激活和停用护栏实例\n- **检测器注册**：支持注册内置检测器和自定义检测器\n- **规则链配置**：定义多个检测器的执行顺序和组合逻辑\n- **运行时配置**：支持热更新检测规则而无需重启应用\n\n### Guard Executor\n\n`GuardExecutor`是护栏系统的执行引擎，负责实际运行安全检查逻辑并返回决策结果。该模块封装了底层的检测算法和策略评估逻辑。\n\n核心职责：\n\n- **检测执行**：调用已注册的检测器对输入/输出进行评估\n- **策略评估**：根据配置的策略规则做出最终决策\n- **结果聚合**：合并多个检测器的结果生成统一报告\n- **异常处理**：处理检测过程中的异常情况并提供降级策略\n\n资料来源：[guardrails_manager.py:1-50]()\n\n## 核心数据结构\n\n安全护栏系统使用以下关键数据结构来描述检测规则和执行结果。\n\n### 检测器定义\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `name` | string | 是 | 检测器唯一标识名称 |\n| `type` | string | 是 | 检测器类型：`builtin`（内置）或 `custom`（自定义） |\n| `description` | string | 否 | 检测器的功能描述 |\n| `config` | dict | 否 | 检测器的配置参数 |\n| `threshold` | float | 否 | 检测阈值，范围0.0-1.0 |\n| `action` | string | 否 | 触发后的动作：`block`、`warn`、`log` |\n\n### 护栏执行结果\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| `passed` | boolean | 是否通过安全检查 |\n| `detections` | list | 检测到的违规项列表 |\n| `scores` | dict | 各检测器的置信度评分 |\n| `action_taken` | string | 实际执行的动作 |\n| `timestamp` | datetime | 执行时间戳 |\n\n资料来源：[guard_executor.py:1-80]()\n\n## 初始化与配置\n\n在使用安全护栏功能之前，需要正确初始化相关的配置。\n\n### 基础配置\n\n安全护栏模块通过RagaAI Catalyst的统一认证体系进行身份验证。开发者需要在环境变量中配置以下凭证：\n\n| 环境变量 | 说明 |\n|----------|------|\n| `RAGAAI_CATALYST_ACCESS_KEY` | RagaAI Catalyst访问密钥 |\n| `RAGAAI_CATALYST_SECRET_KEY` | RagaAI Catalyst秘钥 |\n| `RAGAAI_CATALYST_BASE_URL` | API服务基础URL |\n\n初始化代码示例：\n\n```python\nimport os\nfrom ragaai_catalyst import RagaAICatalyst\n\n# 初始化RagaAI Catalyst客户端\ncatalyst = RagaAICatalyst(\n access_key=os.getenv(\"RAGAAI_CATALYST_ACCESS_KEY\"),\n secret_key=os.getenv(\"RAGAAI_CATALYST_SECRET_KEY\"),\n base_url=os.getenv(\"RAGAAI_CATALYST_BASE_URL\"),\n)\n```\n\n资料来源：[examples/custom_agents/travel_agent/config.py:1-20]()\n\n### 护栏管理器初始化\n\n创建护栏管理器实例并配置检测器：\n\n```python\nfrom ragaai_catalyst import GuardrailsManager\n\n# 创建护栏管理器\nguardrails = GuardrailsManager(\n project_name=\"my_secure_app\",\n dataset_name=\"guardrails_config\",\n detector_config=[\n {\n \"name\": \"harmful_content\",\n \"type\": \"builtin\",\n \"threshold\": 0.7,\n \"action\": \"block\"\n },\n {\n \"name\": \"personal_info\",\n \"type\": \"custom\",\n \"description\": \"检测个人信息泄露\",\n \"threshold\": 0.5,\n \"action\": \"warn\"\n }\n ]\n)\n```\n\n## 内置检测器\n\nRagaAI Catalyst提供了多种内置检测器，覆盖常见的安全风险场景。\n\n### 可用内置检测器\n\n| 检测器名称 | 检测内容 | 默认阈值 |\n|------------|----------|----------|\n| `harmful_content` | 有害内容（暴力、仇恨、自残等） | 0.6 |\n| `stereotypes` | 刻板印象和歧视性内容 | 0.5 |\n| `personal_info` | 个人隐私信息泄露 | 0.7 |\n| `prompt_injection` | 提示词注入攻击 | 0.8 |\n| `toxic_language` | 有毒语言和辱骂性内容 | 0.6 |\n| `misinformation` | 虚假信息和误导性内容 | 0.5 |\n\n### 自定义检测器\n\n除了内置检测器外，开发者可以创建自定义检测器来满足特定业务需求：\n\n```python\n# 定义自定义检测器配置\ncustom_detector = {\n \"name\": \"prevent_sensitive_topics\",\n \"type\": \"custom\",\n \"description\": \"防止讨论敏感话题\",\n \"config\": {\n \"blocked_topics\": [\"politics\", \"religion\", \"conspiracy\"],\n \"match_mode\": \"any\" # 或 \"all\"\n },\n \"threshold\": 0.5,\n \"action\": \"block\"\n}\n```\n\n## 执行流程\n\n安全护栏的执行遵循标准的处理流程，确保每个请求都经过适当的安全检查。\n\n```mermaid\ngraph TD\n A[接收输入请求] --> B[参数验证]\n B --> C{参数有效?}\n C -->|否| D[返回验证错误]\n C -->|是| E[加载检测器配置]\n E --> F[执行输入护栏]\n F --> G[遍历检测器列表]\n G --> H{当前检测器}\n H -->|内置| I[调用内置检测逻辑]\n H -->|自定义| J[调用自定义检测逻辑]\n I --> K[计算风险评分]\n J --> K\n K --> L{评分>=阈值?}\n L -->|是| M[记录违规项]\n L -->|否| N[继续下一检测器]\n M --> O[触发对应动作]\n O --> N\n N --> P{还有检测器?}\n P -->|是| G\n P -->|否| Q[汇总检查结果]\n Q --> R{全部通过?}\n R -->|是| S[转发至LLM处理]\n R -->|否| T[执行拦截/过滤]\n S --> U[获取LLM响应]\n U --> V[执行输出护栏]\n V --> W[返回最终响应]\n T --> W\n```\n\n## 集成使用模式\n\n安全护栏系统支持多种集成方式，以适应不同的应用架构场景。\n\n### 模式一：独立护栏服务\n\n在独立的微服务架构中部署护栏功能：\n\n```python\nfrom ragaai_catalyst import GuardrailsManager, GuardExecutor\n\n# 创建护栏管理器和执行器\nguardrails_manager = GuardrailsManager(\n project_name=\"guardrail_service\",\n detector_config=[...]\n)\n\nguard_executor = GuardExecutor(\n detectors=guardrails_manager.get_detectors()\n)\n\ndef process_request(user_input):\n # 执行输入检查\n result = guard_executor.execute(\n content=user_input,\n direction=\"input\"\n )\n \n if not result.passed:\n return {\"error\": \"内容不符合安全要求\", \"details\": result.detections}\n \n # 继续处理流程\n return llm.process(user_input)\n```\n\n### 模式二：中间件集成\n\n将护栏功能作为中间件集成到现有应用框架中：\n\n```python\nfrom ragaai_catalyst import GuardrailsMiddleware\n\n# 创建护栏中间件\nguardrails_middleware = GuardrailsMiddleware(\n detector_config=[...],\n middleware_config={\n \"log_all_requests\": True,\n \"fail_open\": False # 安全失败模式\n }\n)\n\n# 应用中间件\napp.add_middleware(guardrails_middleware)\n```\n\n资料来源：[quickstart.md:50-100]()\n\n## 最佳实践\n\n### 配置优化建议\n\n1. **分层检测策略**：根据风险等级配置不同的检测器和阈值\n2. **性能权衡**：避免配置过多的高开销检测器\n3. **持续迭代**：定期审查检测结果，优化检测规则\n\n### 安全加固建议\n\n| 场景 | 推荐配置 |\n|------|----------|\n| 用户输入验证 | 启用所有内置检测器，阈值0.6 |\n| 高风险应用 | 添加自定义检测器，启用strict模式 |\n| 低延迟需求 | 减少自定义检测器，预设缓存策略 |\n| 合规要求严格 | 启用完整审计日志，配置双重验证 |\n\n## 错误处理与降级\n\n护栏系统实现了完善的错误处理机制，确保在异常情况下应用仍能正常运行。\n\n### 异常类型\n\n| 异常类型 | 触发条件 | 默认处理 |\n|----------|----------|----------|\n| `DetectorNotFoundError` | 检测器配置错误 | 返回配置错误 |\n| `ExecutionTimeoutError` | 检测超时 | 降级放行并记录 |\n| `ConfigurationError` | 初始化配置错误 | 阻止启动 |\n| `QuotaExceededError` | API配额超限 | 限流处理 |\n\n### 降级策略配置\n\n```python\nguardrails = GuardrailsManager(\n project_name=\"my_app\",\n detector_config=[...],\n fallback_config={\n \"on_detection_error\": \"allow\", # 检测异常时默认放行\n \"on_timeout\": \"allow\", # 超时时默认放行\n \"on_quota_exceeded\": \"block\", # 配额超限默认拦截\n \"log_fallbacks\": True # 记录降级事件\n }\n)\n```\n\n## 相关功能模块\n\n安全护栏管理与RagaAI Catalyst的其他核心功能紧密集成。\n\n```mermaid\ngraph LR\n A[安全护栏管理] --> B[项目管理]\n A --> C[数据集管理]\n A --> D[追踪系统]\n A --> E[评估框架]\n B --> F[统一认证]\n C --> F\n D --> F\n E --> F\n```\n\n- **项目管理**：护栏配置作为项目元数据进行管理\n- **数据集管理**：安全测试数据集用于验证护栏效果\n- **追踪系统**：记录护栏执行事件用于审计分析\n- **评估框架**：评估护栏的检出率和误报率\n\n资料来源：[README.md:1-50]()\n\n## 总结\n\nRagaAI Catalyst的安全护栏管理模块提供了一套完整、可扩展的安全保护解决方案。通过内置检测器与自定义检测器的组合，以及灵活的策略配置机制，开发者能够快速为AI应用构建坚实的安全防线。该模块与RagaAI Catalyst平台的认证系统、项目管理和追踪功能深度集成，为企业级AI应用提供了全方位的安全保障能力。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：raga-ai-hub/RagaAI-Catalyst\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：2.1.7.1。\n\n## 1. 安装坑 · 来源证据：2.1.7.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass.\n\n## 5. 运行坑 · 来源证据：2.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：2.2.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：2.2.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v2.1.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：2.1.6.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daf5807f609141008dc6aaadbc15d774 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：2.1.6.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0790ea07d026457a8eb6bf9e454fdcfa | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：2.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.2.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f1b8373166c14c4dba527f91193c93f1 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Authorization receipts for agent traces — signed governance proof per traced action\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Authorization receipts for agent traces — signed governance proof per traced action\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f70b1d74d8064a45bd97566d464f6f0e | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_534211e56e854a00af1a687847a67d77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：raga-ai-hub/RagaAI-Catalyst\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：2.1.7.1。\n\n## 1. 安装坑 · 来源证据：2.1.7.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass.\n\n## 5. 运行坑 · 来源证据：2.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：2.2.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：2.2.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：v2.1.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：2.1.6.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daf5807f609141008dc6aaadbc15d774 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：2.1.6.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0790ea07d026457a8eb6bf9e454fdcfa | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：2.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.2.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f1b8373166c14c4dba527f91193c93f1 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Authorization receipts for agent traces — signed governance proof per traced action\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Authorization receipts for agent traces — signed governance proof per traced action\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f70b1d74d8064a45bd97566d464f6f0e | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_534211e56e854a00af1a687847a67d77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# RagaAI-Catalyst - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 RagaAI-Catalyst 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Python 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 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. configuration：配置与认证。围绕“配置与认证”模拟一次用户任务，不展示安装或运行结果。\n2. project-management：项目管理。围绕“项目管理”模拟一次用户任务，不展示安装或运行结果。\n3. dataset-management：数据集管理。围绕“数据集管理”模拟一次用户任务，不展示安装或运行结果。\n4. evaluation：评估管理。围绕“评估管理”模拟一次用户任务，不展示安装或运行结果。\n5. agentic-tracing：智能体追踪系统。围绕“智能体追踪系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. configuration\n输入：用户提供的“配置与认证”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. project-management\n输入：用户提供的“项目管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. dataset-management\n输入：用户提供的“数据集管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. evaluation\n输入：用户提供的“评估管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. agentic-tracing\n输入：用户提供的“智能体追踪系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / configuration：Step 1 必须围绕“配置与认证”形成一个小中间产物，并等待用户确认。\n- Step 2 / project-management：Step 2 必须围绕“项目管理”形成一个小中间产物，并等待用户确认。\n- Step 3 / dataset-management：Step 3 必须围绕“数据集管理”形成一个小中间产物，并等待用户确认。\n- Step 4 / evaluation：Step 4 必须围绕“评估管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / agentic-tracing：Step 5 必须围绕“智能体追踪系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/raga-ai-hub/RagaAI-Catalyst\n- https://github.com/raga-ai-hub/RagaAI-Catalyst#readme\n- ragaai_catalyst/ragaai_catalyst.py\n- examples/all_llm_provider/config.py\n- examples/custom_agents/travel_agent/config.py\n- ragaai_catalyst/__init__.py\n- ragaai_catalyst/dataset.py\n- docs/dataset_management.md\n- ragaai_catalyst/evaluation.py\n- ragaai_catalyst/experiment.py\n- ragaai_catalyst/tracers/agentic_tracing/__init__.py\n- ragaai_catalyst/tracers/agentic_tracing/tracers/base.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 RagaAI-Catalyst 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：raga-ai-hub/RagaAI-Catalyst\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install ragaai-catalyst\n```\n\n来源：https://github.com/raga-ai-hub/RagaAI-Catalyst#readme\n\n## 来源\n\n- repo: https://github.com/raga-ai-hub/RagaAI-Catalyst\n- docs: https://github.com/raga-ai-hub/RagaAI-Catalyst#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_25e4e7e68e0a4bbf81b3b4fcc045b8ff"
}