Wayfinder

项目简介

Wayfinder 是一个 AI 应用评测体系的参考实现项目，由开发者 Divakar Ungatla 创建，配套 Medium 文章系列逐步讲解 AI 评测的核心概念与演进路径。整个项目以一个 AI 驱动的航班搜索应用为载体，从最基础的规则化评测开始，逐步引入人工评测、LLM-as-a-Judge、在线评测、实验对比等层次，完整呈现了一个 AI 应用评测体系从零搭建到生产落地的全貌。

这个项目的核心价值不在于航班搜索本身，而在于它回答了一个 AI 工程师在生产环境中必须面对的问题：如何判断自己的 AI 应用是否在变好？如何发现新版本引入的回归？如何规模化地评估 AI 输出的主观质量（如有帮助性、事实性）？

核心功能

• AI 航班搜索参考应用：内置一个完整的 AI 驱动航班搜索应用，作为所有评测方法的统一被测对象，确保每个评测阶段都基于同一个真实可运行的系统。
• 规则化评测（Rule-Based Evaluation）：基于确定性的规则判断 AI 输出是否正确，适合有明确对错标准的场景，如工具调用参数校验、返回格式校验等。
• 人工评测（Human Evaluation）：生成代表性评测数据集（包含用户查询、期望行为、AI 响应、工具输出），供人工评审使用，是主观质量评估的金标准。
• LLM-as-a-Judge：使用大语言模型自动评估 AI 输出的质量，支持本地运行或对接 LangSmith 平台，适合规模化地处理大量评测样本。
• 在线评测（Online Evaluation）：通过真实用户交互追踪（LangSmith tracing），记录用户在生产环境中的实际操作行为与反馈，结合显式反馈数据进行线上效果评估。
• 评测实验对比：支持多轮评测实验的横向对比，自动计算目标指标与回归防护指标，便于量化新版本相对于旧版本的改进或退步。
• LangSmith 集成：开箱即用支持 LangSmith 的追踪与评测能力，包括交互追踪、评测数据集管理、实验结果可视化。
• 目标评测与回归防护：内置 target 和 regression-guard 两种评测用例，既关注新功能是否达到预期，也确保历史功能不被破坏。

技术实现

Wayfinder 的技术栈以 Python 3.12+ 为核心，使用 uv 作为包管理工具。项目结构分为 src/wayfinder/（包含 agent、evaluators、models、services、tools 五大模块）和 examples/（包含各评测方法的实际运行示例）。

评测引擎支持多种 evaluator 类型：RuleBasedEvaluator 通过正则和断言判断确定性输出；HumanEvaluationGenerator 生成结构化评测数据集；LLMJudgeEvaluator 调用 OpenAI API 对开放式响应进行评分；OnlineEvaluator 从 LangSmith 追踪数据中提取真实用户交互片段进行评估。所有 evaluator 均支持重复运行以验证结果稳定性。

数据流方面，评测结果通过 LangSmith 的实验对比视图呈现，支持按时间维度查看指标趋势，并可通过 API 导出为结构化数据用于自定义仪表盘。评测数据集和评分规则（rubrics）以 YAML 文件形式存储，便于版本管理和团队协作。

快速上手

第一步：克隆代码并安装依赖

git clone https://github.com/DivakarUngatla/wayfinder.git
cd wayfinder
uv sync

第二步：配置环境变量

cp .env.example .env
# 填入 OPENAI_API_KEY（用于 LLM-as-a-Judge 和 CLI 交互）
# 填入 LANGSMITH_API_KEY（用于在线评测和实验追踪）

第三步：启动 AI 助手并与之交互

uv run python examples/wayfinder_cli.py

在终端中直接与 AI 航班搜索助手对话，所有交互会被 LangSmith 自动追踪记录。

第四步：运行规则化本地评测

uv run python examples/rule_based_evaluation/local_evaluation.py

基于预置的规则集对 AI 输出进行校验，输出通过/失败结果及详细原因。

第五步：运行 LLM-as-a-Judge 评测

uv run python examples/llm_judge_evaluation/local_evaluation.py

使用 OpenAI 模型对开放式 AI 响应进行质量评分，包括有帮助性、事实性、结构性等多个维度。

适用人群

• AI 应用开发者：正在构建 AI 产品，需要建立系统化的评测流程来保障发布质量。
• AI 工程团队：需要量化 AI 系统的改进与回归，建议将 Wayfinder 的评测框架集成到 CI/CD 流水线中。
• AI 评测研究者：希望获得一个真实可运行的评测参考实现，而非纸上谈兵的概念文档。
• LangChain/LangSmith 用户：Wayfinder 原生集成 LangSmith，现有用户可直接将评测能力迁移到自己的项目中。

官方链接

• GitHub：https://github.com/DivakarUngatla/wayfinder
• 文章系列（Medium）：https://ai.plainenglish.io/software-tests-vs-ai-evals-why-ai-applications-need-a-different-way-of-testing-205b6ae197fb