RAG实验加速器
概述
RAG实验加速器是一款多功能工具,可以帮助您使用Azure AI搜索和RAG模式进行实验和评估。本文档提供了一份全面的指南,涵盖了有关该工具的所有内容,如其目的、特性、安装、使用等。
目的
RAG实验加速器的主要目标是使运行搜索查询和OpenAI响应质量的实验和评估变得更容易、更快捷。该工具对于研究人员、数据科学家和开发人员非常有用,他们希望:
- 测试不同搜索和OpenAI相关超参数的性能。
- 比较各种搜索策略的有效性。
- 调整和优化参数。
- 找到最佳超参数组合。
- 从实验结果生成详细的报告和可视化。
最新更改
2024年3月18日 - 添加了内容采样功能。此功能将允许按指定比例对数据集进行采样。数据按内容聚类,然后在每个聚类中按采样比例取样,以尝试实现采样数据的均匀分布。
这样做是为了确保样本中的代表性结果与整个数据集中得到的结果一致。
注意:如果您之前使用过此工具,建议重建您的环境,因为新增了依赖项。
特性
RAG实验加速器是基于配置驱动的,提供了一套丰富的特性来支持其目的:
-
实验设置:您可以通过指定一系列搜索引擎参数、搜索类型、查询集和评估指标来定义和配置实验。
-
集成:它可以无缝集成Azure AI搜索、Azure机器学习、MLFlow和Azure OpenAI。
-
丰富的搜索索引:它基于配置文件中的超参数配置创建多个搜索索引。
-
多文档加载器:该工具支持多种文档加载器,包括通过Azure Document Intelligence加载和基本的LangChain加载器。这使您能够灵活地实验不同的提取方法并评估其有效性。
-
自定义文档智能加载器:选择“预构布局”API模型用于文档智能时,该工具会使用自定义文档智能加载器来加载数据。该自定义加载器支持将带有列标题的表格格式化为键值对(以增强LLM的可读性),排除文件中与LLM无关的部分(如页码和页脚),使用正则表达式删除文件中的重复模式等。由于每个表格行都被转换为文本行,为避免在中间断开行,通过段落和行递归进行分块。当“预构布局”API模型失败时,自定义加载器会退而求其次使用更简单的“预构布局”API模型。任何其他API模型将使用LangChain的实现,后者返回来自Document Intelligence API的原始响应。
-
查询生成:该工具可以生成多种不同且可定制的查询集,以满足特定的实验需求。
-
多种搜索类型:它支持多种搜索类型,包括纯文本、纯向量、跨向量、多向量、混合等。这使您能够对搜索能力和结果进行全面分析。
-
子查询:该模式评估用户查询,如果发现其足够复杂,会将其拆分为较小的子查询以生成相关的上下文。
-
重新排序:使用LLM重新评估并根据查询与上下文之间的相关性对Azure AI搜索的查询响应进行排名。
-
指标和评估:它支持端到端的指标,将生成的答案(实际)与真实答案(预期)进行比较,包括基于距离、余弦和语义相似性的指标。它还包括基于组件的指标,使用LLM作为评判来评估检索和生成性能,如上下文召回或答案相关性,以及评估搜索结果的检索指标(例如MAP@k)。
-
报告生成:RAG实验加速器自动化了报告生成过程,生成的报告包含易于分析和共享的可视化内容。
-
多语言支持:该工具支持语言分析器,以提供对单个语言的语言支持,以及用于搜索索引用户定义模式的专门(与语言无关)的分析器。更多信息,请参见分析器类型。
使用的产品
- Azure AI搜索服务(注意:语义搜索在Azure AI搜索中可用,基本层或更高)
- Azure OpenAI服务或访问OpenAI API
- Azure机器学习资源
计算设置
目前,RAG实验加速器在桌面计算机上运行。有两种可用的选项:在开发容器中运行或在您的主机上本地安装。
1. 在开发容器中运行
使用开发容器意味着所有必需的软件都会为您安装。这需要WSL。有关开发容器的更多信息,请访问containers.dev
安装先决软件
在您要进行部署的主机上安装以下软件:
在DevContainer中开发
有关设置WSL的进一步指导,请参见这里。现在您已经具备了先决条件,您可以:
- 克隆仓库:在WSL终端中克隆加速器的仓库。
git clone https://github.com/microsoft/rag-experiment-accelerator.git
code .
项目在vscode中打开后,它应该会询问您是否要“在开发容器中重新打开此项目”。请选择是。
数据
将您的文件(PDF、HTML、Markdown、Text、JSON或DOCX格式)复制到“data”文件夹中。
2. 本地安装
当然,如果您愿意,您也可以在Windows/Mac机器上运行RAG实验加速器;您需要负责安装正确的工具。请按照以下安装步骤:
- 克隆仓库:从[GitHub]克隆加速器的仓库。
git clone https://github.com/microsoft/rag-experiment-accelerator.git
- 设置环境文件:复制
.env.template
并保存为.env
文件。为所有键提供值
LOGGING_LEVEL默认为INFO。允许的日志级别有NOTSET、DEBUG、INFO、WARN、ERROR、CRITICAL。
- 在conda(先安装Anaconda/Miniconda)或虚拟环境中执行requirements.txt(需要在运行时安装一些依赖项)以安装依赖项。
conda create -n rag-experiment python=3.11
conda init bash
关闭终端,打开一个新终端,运行:
conda activate rag-experiment
pip install .
- 安装Azure CLI并进行授权:
az login
az account set —subscription="<your_subscription_guid>"
az account show
- 将您的文件(PDF、HTML、Markdown、Text、JSON或DOCX格式)复制到“data”文件夹中。
云设置
有3种选项可安装所有必需的Azure服务:
1. 使用Azure开发CLI安装
此项目支持 Azure Developer CLI。
azd provision
- 如果您喜欢,也可以使用
azd up
,因为这会调用azd provision
- 请使用上/下箭头选择您的订阅和区域
完成后,您可以使用启动配置运行或调试4个步骤,azd
配置的当前环境将加载正确的值。
2. 通过Azure门户UI一键部署Azure
如果您想从模板自行部署基础设施,您也可以点击这里:
3. 使用Azure CLI部署
如果您不想使用 azd
,也可以使用普通的 az
cli。
使用以下命令进行部署。
az login
az deployment sub create --subscription <subscription-id> --location <location> --template-file infra/main.bicep
或者
要使用隔离的网络进行部署,请使用以下命令。用您的隔离网络具体参数替换参数值。如果要部署到隔离网络,您必须提供这三个参数(即 vnetAddressSpace
、proxySubnetAddressSpace
和 subnetAddressSpace
)。
az login
az deployment sub create --location <location> --template-file infra/main.bicep \
--parameters vnetAddressSpace=<vnet-address-space> \
--parameters proxySubnetAddressSpace=<proxy-subnet-address-space> \
--parameters subnetAddressSpace=<azure-subnet-address-space>
以下是带参数值的示例:
az deployment sub create --location uksouth --template-file infra/main.bicep \
--parameters vnetAddressSpace='10.0.0.0/16' \
--parameters proxySubnetAddressSpace='10.0.1.0/24' \
--parameters subnetAddressSpace='10.0.2.0/24'
如何使用
要使用RAG实验加速器,请按照以下步骤:
- 将提供的
config.sample.json
文件复制为一个名为config.json
的文件,并根据您的实验调整任何超参数。 - 运行
01_index.py
(python 01_index.py) 以创建Azure AI Search索引并将数据加载到其中。
python 01_index.py
-d "保存配置文件和数据的目录。默认为当前工作目录"
-dd "保存数据的目录。默认为data"
-cf "JSON配置文件名。默认为config.json"
- 运行
02_qa_generation.py
(python 02_qa_generation.py) 以使用Azure OpenAI生成问答对。
python 02_qa_generation.py
-d "保存配置文件和数据的目录。默认为当前工作目录"
-dd "保存数据的目录。默认为data"
-cf "JSON配置文件名。默认为config.json"
- 运行
03_querying.py
(python 03_querying.py) 以查询Azure AI Search生成上下文、重新排列上下文中的项目,并使用新上下文从Azure OpenAI获取响应。
python 03_querying.py
-d "保存配置文件和数据的目录。默认为当前工作目录"
-cf "JSON配置文件名。默认为config.json"
- 运行
04_evaluation.py
(python 04_evaluation.py) 以使用各种方法计算指标,并在Azure Machine Learning中通过MLFlow集成生成图表和报告。
python 04_evaluation.py
-d "保存配置文件和数据的目录。默认为当前工作目录"
-cf "JSON配置文件名。默认为config.json"
或者,你可以使用Azure ML流水线运行上述步骤(除了02_qa_generation.py
)。要这样做,请按照此处的指南。
配置元素说明
{
"index_name_prefix": "搜索索引名称前缀",
"experiment_name": "如果提供,这将是Azure ML中的实验名称,并且它会将所有作业运行分组到相同的实验中,否则(如果留空)将使用index_name_prefix,并且可能会有多个实验",
"job_name": "如果提供,Azure ML中的所有作业运行将使用此属性值加上时间戳命名,否则(如果留空)每个作业将仅用时间戳命名",
"job_description": "您可以为当前的作业运行提供描述,描述您即将进行的实验",
"sampling": {
"sample_data": "设置为true以启用采样",
"sample_percentage": "要采样的文档语料库的百分比",
"optimum_k": "设置为'auto'以自动确定最佳簇数,或设置为特定值,例如15",
"min_cluster": "用于自动最佳簇过程,这是最小簇数,例如2",
"max_cluster": "用于自动最佳簇过程,这是最大簇数,例如30"
},
"chunking": {
"chunk_size": "每个块的大小,例如[500, 1000, 2000]" ,
"overlap_size": "每个块的重叠大小,例如[100, 200, 300]"
},
"embedding_models": "参见下文的'嵌入模型配置说明'",
"embedding_dimension" : "每个块的嵌入大小,例如[384, 1024]。有效值为384, 768, 1024",
"ef_construction" : "ef_construction值决定了Azure AI Search向量配置的值",
"ef_search": "ef_search值决定了Azure AI Search向量配置的值",
"language": {
"analyzer_name" : "在字段中使用的分析器的名称。此选项只能与可搜索字段一起使用,不能与searchAnalyzer或indexAnalyzer一起设置",
"index_analyzer_name" : "用于字段索引时间的分析器名称。此选项只能与可搜索字段一起使用。必须与searchAnalyzer一起设置,并且不能与analyzer选项一起设置",
"search_analyzer_name" : "用于字段搜索时间的分析器的名称。此选项只能与可搜索字段一起使用。必须与indexAnalyzer一起设置,并且不能与analyzer选项一起设置。此属性不能设置为语言分析器的名称;如果需要语言分析器,请使用analyzer属性"
},
"experiment_name": "实验名称",
"rerank": "决定搜索结果是否应该重新排序。有效值为TRUE或FALSE" ,
"rerank_type": "决定重新排序的类型。有效值为llm或crossencoder",
"llm_re_rank_threshold": "使用llm重新排序时的阈值。评分高于此数字的块在1到10之间选择",
"cross_encoder_at_k": "使用交叉编码重新排序的阈值。选择具有给定排名值的块",
"crossencoder_model" :"用于交叉编码重新排序步骤的模型。有效值为cross-encoder/stsb-roberta-base",
"search_types" : "用于实验的搜索类型。有效值为search_for_match_semantic, search_for_match_Hybrid_multi, search_for_match_Hybrid_cross, search_for_match_text, search_for_match_pure_vector, search_for_match_pure_vector_multi, search_for_match_pure_vector_cross, search_for_manual_hybrid。例如['search_for_manual_hybrid', 'search_for_match_Hybrid_multi','search_for_match_semantic' ]",
"retrieve_num_of_documents": "确定从搜索索引中检索的块数",
"metric_types" : "用于评估的指标(端到端或基于组件使用LLM的指标)。端到端指标的有效值为lcsstr, lcsseq, cosine, jaro_winkler, hamming, jaccard, levenshtein, fuzzy, bert_all_MiniLM_L6_v2, bert_base_nli_mean_tokens, bert_large_nli_mean_tokens, bert_large_nli_stsb_mean_tokens, bert_distilbert_base_nli_stsb_mean_tokens, bert_paraphrase_multilingual_MiniLM_L12_v2。基于组件的LLM指标的有效值为llm_answer_relevance, llm_context_precision和llm_context_recall。例如['fuzzy','bert_all_MiniLM_L6_v2','cosine','bert_distilbert_base_nli_stsb_mean_tokens', 'llm_answer_relevance']",
"azure_oai_chat_deployment_name": "决定Azure OpenAI部署名称",
"azure_oai_eval_deployment_name": "评估使用的Azure OpenAI部署名称",
"embedding_model_name": "嵌入模型名称",
"openai_temperature": "决定OpenAI的温度。有效值范围为0到1",
"search_relevancy_threshold": "确定文档是否相关的相似度阈值。有效范围为0.0到1.0",
"chunking_strategy": "决定分块策略。有效值为'azure-document-intelligence'或'basic'",
"query_expansion": "此功能允许您尝试各种查询扩展方法,以可能提高检索指标。可能的值为'disabled'(默认),'generated_hypothetical_answer','generated_hypothetical_document_to_answer','generated_related_questions'。参考文章 - [Precise Zero-Shot Dense Retrieval without Relevance Labels (HyDE - Hypothetical Document Embeddings)](https://arxiv.org/abs/2212.10496)",
"min_query_expansion_related_question_similarity_score": "与原始查询的最小相似度得分百分比。默认90%",
"azure_document_intelligence_model": "代表Azure Document Intelligence模型。当使用'azure-document-intelligence'作为分块策略时使用。设置为'prebuilt-layout'提供附加功能(参见上文)"
}
注意:更改配置时,请记得同时更改
config.sample.json
(供他人复制的示例配置)和Github actions配置文件以供CI上的测试使用。
嵌入模型配置说明
embedding_models
是一个数组,包含要使用的嵌入模型的配置。嵌入模型的type
必须为Azure OpenAI模型的azure
或HuggingFace句子变换器模型的sentence-transformer
。
Azure OpenAI嵌入模型配置
{
"type": "azure",
"deployment_name": "模型的部署名称",
"dimension": "嵌入模型的维度。默认为1536,即text-embedding-ada-002的维度"
}
句子变换器嵌入模型
{
"type": "sentence-transformer",
"model_name": "句子变换器模型的名称",
"dimension": "模型的维度。如果模型名称为['all-MiniLM-L6-v2', 'all-mpnet-base-v2', 'bert-large-nli-mean-tokens]之一,则此字段不是必需的"
}
查询扩展
给出查询中的问题的假设答案、包含查询答案的假设段落或生成几个相关问题,可能会改善检索结果,从而获得更准确的文档块以传递到LLM上下文。 参见参考文章 - Precise Zero-Shot Dense Retrieval without Relevance Labels (HyDE - Hypothetical Document Embeddings)
以下配置选项开启相关实验方法:
为查询中的问题生成假设答案
{
"query_expansion": "generated_hypothetical_answer"
}
生成包含查询问题答案的假设文档
{
"query_expansion": "generated_hypothetical_document_to_answer"
}
为查询问题生成相关问题
此功能将生成相关问题,筛选出那些与原始查询的相似度得分低于min_query_expansion_related_question_similarity_score
百分比的问题(使用余弦相似度得分),并将每个问题与原始查询一起搜索文档,去重结果并返回到重排序和top k步骤。
min_query_expansion_related_question_similarity_score
的默认值设置为90%,您可以在config.json
中更改此值
{
"query_expansion": "generated_related_questions",
"min_query_expansion_related_question_similarity_score": 90
}
报告
该解决方案集成了Azure Machine Learning,并使用MLFlow管理实验、作业和工件。您可以在评估过程中查看以下报告:
指标比较
all_metrics_current_run.html
显示每个所选指标的问题和搜索类型的平均分数:
指标分析
在输出的 CSV 文件中,每个问题和搜索类型的每个指标的计算和用于评估的字段都被跟踪:
超参数
样本指标
可以在不同运行之间比较指标:
搜索评估
可以在不同搜索策略之间比较指标:
检索评估
平均精度得分被记录下来,并可以在不同的搜索类型之间进行比较:
陷阱
本节概述了工程师/开发人员/数据科学家在使用 RAG 实验加速器时可能遇到的常见问题或陷阱。
Azure 身份验证和授权
描述:
为了成功使用此解决方案,您必须首先通过登录您的 Azure 帐户进行身份验证。这是一个基本步骤,以确保您拥有访问和管理 Azure 资源所需的权限。您可能会因为对 Azure 不适当的授权和身份验证而导致将 QnA 数据存储到 Azure 机器学习数据资产、执行查询和评估步骤时出现错误。请参见本文档中的第 4 点以进行身份验证和授权。
可能会有一种情况,即使身份验证和授权有效,解决方案仍会生成错误。在这种情况下,使用一个全新的终端实例启动一个新会话,按照第 4 步中的步骤登录 Azure,并检查用户是否具有与解决方案相关的 Azure 资源的贡献访问权限。
配置
描述
此解决方案在 config.json 中使用了多个直接影响其功能和性能的配置参数。请特别注意这些设置:
retrieve_num_of_documents: 此配置控制初始分析中检索的文档数量。值过高或过低可能会导致“索引超出范围”错误,因为排名处理的搜索 AI 结果。 cross_encoder_at_k: 此配置影响排名过程。较高的值可能导致无关的文档被包含在最终结果中。 llm_re_rank_threshold: 此配置决定传递给语言模型 (LLM) 进行进一步处理的文档。将此值设置得太高可能会为 LLM 创建过大的上下文,可能导致处理错误或结果下降。这也可能导致来自 Azure OpenAI 端点的异常。
Azure OpenAI 模型和部署
描述
在运行此解决方案之前,请确保您在 config.json 文件中正确设置了 Azure OpenAI 部署名称,并将相关密钥添加到环境变量 (.env 文件) 中。此信息对于应用程序连接到适当的 Azure OpenAI 资源并正常运行至关重要。如果您不确定配置数据,请参阅 .env.template 和 config.json 文件。该解决方案已在 GPT 3.5 turbo 模型上测试过,需要对其他模型进行进一步测试。
问题生成和查询步骤
描述
在 QnA 生成步骤中,您可能会偶尔遇到与从 Azure OpenAI 接收到的 JSON 输出相关的错误。这些错误可能会阻止成功生成某些问题和答案。以下是您需要了解的信息:
可能的原因:
格式不正确: 从 Azure OpenAI 输出的 JSON 可能不遵循预期格式,导致 QnA 生成过程出现问题。 内容过滤: Azure OpenAI 具有内容过滤功能。如果输入文本或生成的响应被视为不合适,可能会导致错误。 API 限制: Azure OpenAI 服务具有令牌和速率限制,影响输出。
评估步骤
描述
端到端评估指标: 并不是所有比较生成答案和真实答案的指标都能捕捉语义上的差异。例如,levenshtein
或 jaro_winkler
等指标仅测量编辑距离。cosine
指标也不能进行语义比较:它使用基于术语频率向量的 textdistance 令牌实现。要计算生成答案与预期答复之间的语义相似度,请考虑使用基于嵌入的指标,如 Bert 分数 (bert_
)。
组件级评估指标: 使用 LLM 作为评价者的评估指标并不是确定性的。加速器中包含的 llm_
指标使用配置字段 azure_oai_eval_deployment_name
中指定的模型。用于评估指令的提示可以调整,并包含在 prompts.py
文件中(llm_answer_relevance_instruction
, llm_context_recall_instruction
, llm_context_precision_instruction
)。
基于检索的指标: 通过将每个检索到的块与问题和用于生成 QnA 对的块进行比较来计算 MAP 得分。要评估某个检索到的块是否相关,使用 SpacyEvaluator 计算检索到的块与最终用户问题和 QnA 步骤 (02_qa_generation.py
) 中使用的块组合之间的相似度。Spacy 相似度默认为令牌向量的平均值,这意味着计算对单词顺序不敏感。默认情况下,相似度阈值设置为 80% (spacy_evaluator.py
)。
贡献
我们欢迎您的贡献和建议。要进行贡献,您需要同意一个 贡献者许可协议(CLA),确认您有权利并实际授予我们使用您贡献的权利。有关详细信息,请访问 [https://cla.opensource.microsoft.com]。
当您提交一个拉取请求(PR)时,CLA 机器人会自动检查您是否需要提供 CLA 并给出指示(例如,状态检查、评论)。按照机器人的指示操作。对于所有使用我们 CLA 的仓库,您只需执行一次此操作。
在您贡献之前,确保运行
pip install -e .
pre-commit install
此项目遵循 Microsoft 开源行为规范。 有关更多信息,请参阅 行为规范常见问题,或者联系 opencode@microsoft.com 以获取任何问题或评论。
开发人员贡献指南
- 分支命名约定:
- 使用 GitHub UI 在分支名称中包含一个标签,然后直接从 UI 创建分支。以下是一些示例:
bug/11-short-description
feature/22-short-description
- 使用 GitHub UI 在分支名称中包含一个标签,然后直接从 UI 创建分支。以下是一些示例:
- 合并更改:
- 在合并时,将您的提交压缩为最多 3 个增量提交,以供拉取请求(PR)和合并。
- 项目维护者可以从贡献者合并已接受的代码更改,或者贡献者可以请求仓库的写权限,以便在项目维护者审核后合并拉取请求。
- 项目维护者可以通过电子邮件联系。
- 分支卫生:
- 合并后删除分支。
- 本地测试更改:
- 在合并之前,本地测试您的更改。
- 命名约定:
- 对指标名称和配置变量使用蛇形命名法,例如
example_snake_case
。 - 将您的 Git 用户名设置为您的名字和姓氏,如此:
git config --global user.name "First Last"
- 对指标名称和配置变量使用蛇形命名法,例如
- 问题跟踪:
商标
此项目可能包含项目、产品或服务的商标或标识。您必须遵循Microsoft 的商标和品牌使用指南来正确使用 Microsoft 商标或标识。 不要在本项目的修改版本中使用 Microsoft 商标或标识,以免引起混淆或暗示 Microsoft 的赞助。 遵循本项目包含的任何第三方商标或标识的使用政策。