基于 azure-search-openai-demo 的 RAG 答案质量评估：从评测模型部署到结果审查的完整实践指南

基于 azure-search-openai-demo 的 RAG 答案质量评估从评测模型部署到结果审查的完整实践指南【免费下载链接】azure-search-openai-demoA sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demoRAG检索增强生成系统的答案质量如何量化本文基于开源仓库 azure-search-openai-demo 中的 docs/evaluation.md 文档系统讲解一套完整的 RAG 答案质量评估方案如何部署专用评测模型、如何用 RAGAS 生成 ground truth标准答案数据、如何批量运行评估并审查结果以及如何评估多模态 RAG 答案。读完本文你将掌握从零搭建一条可复用的评估流水线、读懂各评估指标含义、并通过结果对比持续优化问答质量的方法。评估的整体思路RAG 答案质量的评估本质上是一种「离线批量评测」预先准备一批「问题 标准答案」的 ground truth 数据然后把这些问题逐一发给正在运行的聊天应用收集应用返回的答案与引用来源再让一个专门的评测模型judge model对答案打分最后汇总出各项指标的统计结果。这个流程在仓库中的落地路径非常清晰evals/generate_ground_truth.py生成 ground truth 数据evals/run_evaluate.py执行批量评估的入口脚本evals/evaluate_config.json评估配置指标、目标 URL、请求参数等evals/evaltools/评估结果汇总与对比工具summary、diff命令evals/results/每次评估运行的输出目录每个运行目录内包含eval_results.jsonl、summary.json、evaluate_parameters.json、config.json。整个评估流程分为五步部署评测模型 → 搭建评估环境 → 生成 ground truth → 运行批量评估 → 审查结果。第一步部署一个专用的评测模型评估需要大语言模型来生成标准答案并为答案打分因此首先要通过azd部署一个「推理型reasoning评测模型」。开启评测部署在部署目录下执行azd env set USE_EVAL trueUSE_EVAL环境变量告诉azd在部署时额外创建评测模型的部署。同时建议把评测模型和聊天模型的容量capacity都调到最高值因为批量评估期间两个部署都可能被限流评测模型负责给答案打分聊天模型负责生成标准答案和查询改写query rewrite任一端被限流都会拖慢整个评估azd env set AZURE_OPENAI_EVAL_DEPLOYMENT_CAPACITY 100 azd env set AZURE_OPENAI_CHATGPT_DEPLOYMENT_CAPACITY 100选择评测模型默认情况下评测部署使用gpt-5.4、版本2026-03-05。如需更换可设置以下 azd 环境变量AZURE_OPENAI_EVAL_MODEL评测模型名AZURE_OPENAI_EVAL_MODEL_VERSION模型版本。配置完成后执行azd provision完成资源部署azd provision从源码看evals/run_evaluate.py 在运行时读取AZURE_OPENAI_EVAL_MODEL作为打分模型读取AZURE_OPENAI_EVAL_DEPLOYMENT作为部署名并把AZURE_OPENAI_ENDPOINT作为 Azure OpenAI 端点evals/generate_ground_truth.py 则用AZURE_OPENAI_EVAL_DEPLOYMENTAZURE_OPENAI_EVAL_MODEL驱动 RAGAS 的测试集生成用AZURE_OPENAI_EMB_DEPLOYMENTAZURE_OPENAI_EMB_MODEL_NAME驱动向量嵌入。这些环境变量通常在azd up/azd provision时写入.azure环境文件评估脚本会通过dotenv_azd的load_azd_env()自动加载见 evals/run_evaluate.py。第二步搭建评估环境评估脚本的依赖与主项目存在版本不兼容因此官方明确要求使用独立的 Python 虚拟环境python -m venv .evalenvsource .evalenv/bin/activate然后安装评估脚本的全部依赖pip install -r evals/requirements.txtevals/requirements.txt 中的关键依赖包括ragas0.2.13RAGAS 测试集生成与知识图谱工具azure-ai-evaluation1.18.0Azure 官方评测库。版本必须不低于 1.18.0因为仓库中的评测器以is_reasoning_modelTrue构造以发送max_completion_tokens而非max_tokens——推理模型如 gpt-5会拒绝max_tokens参数见 evals/evaltools/eval/evaluate_metrics/builtin_metrics.py 中的注释openai1.56.1、azure-search-documents、azure-identity访问 Azure OpenAI 与 AI Searchjmespath、pandas、requests解析响应、聚合统计、发起 HTTP 请求typer、rich提供python -m evaltools命令行与进度显示。第三步生成 ground truth 数据运行生成脚本在激活虚拟环境后执行python evals/generate_ground_truth.py --numquestions200 --numsearchdocs1000脚本会从 Azure AI Search 索引拉取文档分块构建 RAGAS 知识图谱再由评测 LLM 自动生成「问题 → 标准答案含引用」对最终追加写入evals/ground_truth.jsonl。参数说明参数含义建议numquestions要生成的问题数量官方建议至少 200numsearchdocs从搜索索引拉取的文档分块数量可省略以拉取全部文档但会显著增加生成时间建议先用子集起步kgfile已存在的 RAGAS 知识库 JSON 文件通常是ground_truth_kg.json已建过知识库、只想调整问题生成环节时可指定避免重建groundtruthfile生成结果写入的文件默认evals/ground_truth.jsonl️ 注意生成过程耗时可能长达数小时具体取决于搜索索引的大小。生成过程背后的原理从 evals/generate_ground_truth.py 的源码可以看到完整链路通过SearchClient以search_text*拉取索引文档num_search_documents为None时默认取 100000 上限见 evals/generate_ground_truth.py把每个分块的content与sourcepage封装为 RAGASNode构建KnowledgeGraph并调用default_transforms()做图变换如抽取摘要、关系等保存为ground_truth_kg.json用TestsetGenerator基于知识图谱生成指定数量的问题从每个样本的reference_contexts中用正则\[\[(.*?)\]\]提取引用citation追加到标准答案末尾使每条 ground truth 都带有[文档名#pageN]形式的引用标注。实际生成的 ground truth 数据形如摘自仓库 evals/ground_truth.jsonl{question: What protection does Zava offer against balance billing?, truth: Zava offers a balance billing protection through the Northwind Standard plan, which protects employees from unexpected costs when visiting in-network providers. [Northwind_Standard_Benefits_Details.pdf#page7]}人工审核生成完成后务必打开evals/ground_truth.jsonl人工检查删除任何不像真实用户输入的问答对。自动生成的问题质量直接决定评估结果的可信度这一步不能跳过。第四步运行批量评估检查评估配置运行前先检查 evals/evaluate_config.json确保各项配置正确{ testdata_path: ground_truth.jsonl, results_dir: results/experimentTIMESTAMP, requested_metrics: [gpt_groundedness, gpt_relevance, answer_length, latency, citations_matched, any_citation], target_url: http://localhost:50505/chat, target_parameters: { overrides: { top: 5, results_merge_strategy: interleaved, temperature: 0.3, minimum_reranker_score: 0, minimum_search_score: 0, retrieval_mode: hybrid, semantic_ranker: true, semantic_captions: false, query_rewriting: false, reasoning_effort: low, suggest_followup_questions: false, use_oid_security_filter: false, use_groups_security_filter: false, search_text_embeddings: true, search_image_embeddings: true, send_text_sources: true, send_image_sources: true, language: en, use_agentic_knowledgebase: false, seed: 1 } }, target_response_answer_jmespath: output_text, target_response_context_jmespath: context.data_points.text }关键配置项解读testdata_pathground truth 文件路径相对evals/目录results_dir结果输出目录TIMESTAMP占位符会被替换为当前 Unix 时间戳从而为每次运行生成独立目录见 evals/evaltools/eval/evaluate.py 的process_config逻辑requested_metrics本次评估启用的指标列表target_url被测应用的聊天端点。仓库约定本地运行时的地址为http://localhost:50505/chattarget_parameters.overrides发送给应用的请求参数对应前端的开发设置面板可据此固定检索模式、top K、温度、语义排序开关等确保不同轮次评估的「对照条件」一致target_response_answer_jmespath/target_response_context_jmespath用 JMESPath 从应用响应中提取答案与上下文引用的字段路径。执行评估默认情况下脚本会评估 ground truth 中的全部问题。直接运行python evals/run_evaluate.py可选参数参数含义默认值numquestions只评估前 N 个问题全部问题resultsdir结果输出目录时间戳目录也可写在evaluate_config.json中targeturl被测应用的 URLhttp://localhost:50505也可写在配置中️ 批量评估可能耗时数小时取决于 ground truth 问题数量、评测模型 TPM 容量以及启用的 LLM 指标数量。评估器内部工作机制理解评估器如何工作有助于解读结果。核心逻辑位于 evals/evaltools/eval/evaluate.py健康检查正式评估前先向target_url发送一条测试问题What information is in your knowledge base?并向 GPT 部署发送一条responses.create测试请求任一步失败都会中止评估evals/evaltools/eval/evaluate.py逐题评测对每条 ground truth 问题向目标应用发送 POST 请求超时 120 秒见TARGET_REQUEST_TIMEOUT用 JMESPath 提取answer与context记录latencyevals/evaltools/eval/evaluate.py串行执行为避免触发限流评估逐条串行进行代码注释明确 Run evaluations in serial to avoid rate limiting见 evals/evaltools/eval/evaluate.py产出三份文件eval_results.jsonl逐题明细、summary.json指标聚合统计、evaluate_parameters.json本次运行的模型、时间戳、目标 URL、请求参数等元信息并把原始配置复制为config.json便于复现evals/evaltools/eval/evaluate.py。第五步审查评估结果查看所有运行汇总cd evals python -m evaltools summary results该命令汇总evals/results下所有运行目录的指标统计便于横向对比多次实验。对比答案与 ground truthcd evals python -m evaltools diff results/RUNHERE把RUNHERE替换为evals/results下的某个运行目录名即可逐题对比模型答案与标准答案。对比两次运行cd evals python -m evaltools diff results/FIRSTRUNHERE results/SECONDRUNHERE把FIRSTRUNHERE、SECONDRUNHERE替换为两个运行目录名可直接比较两次实验在各项指标与具体回答上的差异。仓库自带的 evals/results_comparisons/ 目录中就有大量这样的对比产物如gpt54-agentic-vs-baseline.md可作为输出样式的参考。summary与diff命令由 evals/evaltools/cli.py 提供内部调用 evals/evaltools/review/summary_markdown.py 与 evals/evaltools/review/diff_markdown.py 生成 Markdown 报告。注意排查隐藏的限流Azure SDK 会自动重试 HTTP 429 响应因此一次评估请求最终可能「成功」但实际花费了大量时间等待容量——而评估客户端只能看到最终成功的结果延迟数据会被限流污染。当目标部署启用了 Application Insights 时可在每次运行后用以下 Kusto 查询检查是否存在限流dependencies | where timestamp between (datetime(RUN_START_UTC) .. datetime(RUN_END_UTC)) | where resultCode 429 | summarize attemptscount(), affectedRequestsdcount(operation_Id) by target, name只要返回了任何行就说明本次延迟结果受到了限流影响。正确做法是提高对应部署的容量 → 重新执行azd provision→ 重跑评估然后再比较延迟。评估指标详解仓库的指标系统位于 evals/evaltools/eval/evaluate_metrics/通过metrics_by_name注册表按名称查找见 evals/evaltools/eval/evaluate_metrics/init.py并支持register_metric()注册自定义指标。默认配置启用了 6 个指标LLM 判定类指标基于评测模型打分gpt_groundedness有据性答案是否忠实于检索到的上下文不编造内容gpt_relevance相关性答案与问题的相关程度。这两类指标底层使用azure-ai-evaluation提供的GroundednessEvaluator/RelevanceEvaluator并以 15 分打分。聚合统计通过get_aggregate_stats_for_numeric_rating计算pass_count得分 ≥ 4 的数量、pass_rate通过率和mean_rating平均分无效打分会被剔除见 evals/evaltools/eval/evaluate_metrics/base_metric.py。代码判定类指标不依赖 LLManswer_length答案字符数输出mean/max/minlatency请求耗时秒输出mean/max/mincitations_matched答案中命中 ground truth 引用的比例命中引用数 ÷ 标准答案引用总数输出total/rateany_citation答案中是否出现任意引用输出total/rate。引用判定使用 evals/evaltools/eval/evaluate_metrics/code_metrics.py 中的CITATION_REGEX可识别[文档.pdf#page7]、[文档.pdf#page4(figure4_1.png)]等格式覆盖 pdf、html、doc、ppt、xls、csv、txt、json 及常见图片格式。其他可用指标注册表中还内置了gpt_coherence连贯性、gpt_similarity相似度、gpt_fluency流畅度、f1_scoreF1等可通过在evaluate_config.json的requested_metrics中增删来启用或关闭。官方文档建议参考 ai-rag-chat-evaluator 的 README 了解全部可用指标其核心能力即在本仓库的evaltools中落地实现。评估多模态 RAG 答案仓库还提供了专门评估多模态 RAG 答案的配置 evals/evaluate_config_multimodal.json使用不同的 ground truth 文件ground_truth_multimodal.jsonl其中包含基于示例数据生成、需要同时依赖文本与图片来源才能回答的问题结果输出到results_multimodal/目录仓库 evals/results_multimodal/ 中已有 baseline、no-image-embeddings、no-image-sources 等对照实验默认启用的指标为gpt_relevance、answer_length、latency、citations_matched、any_citation。需要特别注意groundedness评估器对多模态 RAG 并不可靠因为它目前不把图片来源纳入考量。官方虽然仍在指标中保留了它但更可信的指标是relevance与citations matched。从 evals/evaltools/eval/evaluate_metrics/code_metrics.py 的CITATION_REGEX也可以印证这一点——它已内置(figure4_1.png)这类图片子资源引用格式的匹配专门用于多模态场景下的引用核对。一次完整的评估实践小结把上述步骤串起来一次完整的评估实践是azd env set USE_EVAL true并调高AZURE_OPENAI_EVAL_DEPLOYMENT_CAPACITY与AZURE_OPENAI_CHATGPT_DEPLOYMENT_CAPACITY然后azd provision部署评测模型创建独立虚拟环境并pip install -r evals/requirements.txtpython evals/generate_ground_truth.py --numquestions200 --numsearchdocs1000生成并人工审核evals/ground_truth.jsonl检查 evals/evaluate_config.json确认指标、目标 URL 与请求参数然后python evals/run_evaluate.py用python -m evaltools summary results查看汇总用python -m evaltools diff results/RUN1 results/RUN2对比两次实验用 Kusto 查询排除限流干扰后再根据指标差异迭代调优检索参数、提示词或重排序策略。这套流水线让 RAG 应用的每一次改动检索模式、top K、语义排序、提示词模板等都能得到可量化、可复现的质量反馈是持续优化问答体验的必备基础设施。【免费下载链接】azure-search-openai-demoA sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考