# Pitfall Log / 踩坑日志 项目：vibrantlabsai/ragas 摘要：发现 22 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add EvaluationResult summary and threshold checks。 ## 1. 安装坑 · 来源证据：Add EvaluationResult summary and threshold checks - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add EvaluationResult summary and threshold checks - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2760 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Incorrect class name in deprecation warning for LLMContextPrecisionWithoutReference - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Incorrect class name in deprecation warning for LLMContextPrecisionWithoutReference - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2748 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：No module named 'langchain_community.chat_models.vertexai' - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No module named 'langchain_community.chat_models.vertexai' - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2741 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：ragas 0.4.3: ChatVertexAI import broken — uses removed langchain_community path - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ragas 0.4.3: ChatVertexAI import broken — uses removed langchain_community path - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2745 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 来源证据：answer_correctness is not working as expected - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：answer_correctness is not working as expected - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2585 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 配置坑 · 来源证据：faithfulness_score: nan - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：faithfulness_score: nan - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/1309 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 配置坑 · 来源证据：llm_factory raises ValueError when using mistralai client - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：llm_factory raises ValueError when using mistralai client - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2774 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 8. 安全/权限坑 · 来源证据：AspectCritic not working with openai o3 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AspectCritic not working with openai o3 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2067 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 9. 安全/权限坑 · 来源证据：Feature request: Add AgentThreatBench memory poison task as a RAG security evaluation - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: Add AgentThreatBench memory poison task as a RAG security evaluation - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2732 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 安全/权限坑 · 来源证据：Make python-diskcache dependency optional - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Make python-diskcache dependency optional - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2622 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 安全/权限坑 · 来源证据：No persona found with name : Documentation example doesn't work with minimal changes - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No persona found with name : Documentation example doesn't work with minimal changes - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 安全/权限坑 · 来源证据：Proposal: Contribute English/Uzbek Multilingual RAG Evaluation Dataset to RAGAS - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: Contribute English/Uzbek Multilingual RAG Evaluation Dataset to RAGAS - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2649 | 来源类型 github_issue 暴露的待验证使用条件。 ## 13. 安全/权限坑 · 来源证据：[Security] Agentic Workflow Injection in Claude Docs Check - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] Agentic Workflow Injection in Claude Docs Check - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2692 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 14. 安全/权限坑 · 来源证据：get_token_usage_for_bedrock always returns 0 (reads wrong response_metadata keys for langchain-aws ChatBedrock/ChatBedr… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：get_token_usage_for_bedrock always returns 0 (reads wrong response_metadata keys for langchain-aws ChatBedrock/ChatBedrockConverse) - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2779 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 15. 配置坑 · 来源证据：EmbeddingUsageEvent telemetry NaNs a metric when embeddings expose a non-string .model (e.g. fastembed) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：EmbeddingUsageEvent telemetry NaNs a metric when embeddings expose a non-string .model (e.g. fastembed) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2783 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 16. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/vibrantlabsai/ragas | README/documentation is current enough for a first validation pass. ## 17. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/vibrantlabsai/ragas | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/vibrantlabsai/ragas | no_demo; severity=medium ## 19. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/vibrantlabsai/ragas | no_demo; severity=medium ## 20. 安全/权限坑 · 来源证据：TypeError: unsupported operand type(s) for += on dict when using LangchainLLMWrapper with evaluate() in 0.4.3 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TypeError: unsupported operand type(s) for += on dict when using LangchainLLMWrapper with evaluate() in 0.4.3 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2790 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 21. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/vibrantlabsai/ragas | issue_or_pr_quality=unknown ## 22. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/vibrantlabsai/ragas | release_recency=unknown