AI检索增强生成（加强版）_API 网关(API Gateway)-阿里云帮助中心

本文介绍AI检索增强生成（加强版）及其使用方法。

功能说明

通过对接主流RAG引擎实现LLM调用前的自动检索增强生成，支持RARFlow和百炼知识库。

运行属性

插件执行阶段：默认阶段。
插件执行优先级：400。

配置说明

基本配置

名称	数据类型	填写要求	默认值	描述
`rag.rag_engine_type`	string	必填	-	RAG引擎类型，支持的枚举类型包括: ragflow、bailian。
`result_placement_type`	string	选填	append	支持用户模板替换占位符，如果选择replace，则System提示词模板中的占位符`{{higressRagResultReplacementKey}}`会被替换为RAG生成的内容，如果选择append，则RAG生成的内容会被追加到用户模板中，支持的枚举类型包括: append、replace。

RAGFlow配置

当选择RAGFlow作为RAG引擎时（rag.rag_engine_type=ragflow），请参考以下说明进行配置。

名称	数据类型	填写要求	默认值	描述
`rag.ragflow.api_key`	string	必填	-	调用RAGFlow API的API Key，可在RAGFlow控制台右上角头像-API-RAGFlow API处获取。
`rag.ragflow.serviceFQDN`	string	必填	-	RAGFlow在AI网关的服务名。
`rag.ragflow.servicePort`	string	必填	-	RAGFlow在AI网关的服务端口。
`rag.ragflow.dataset_ids`	list[string]	必填	-	检索RAGFlow的DataSet ID。
`rag.ragflow.serviceHost`	string	选填	-	AI网关访问RAGFlow时域名。
`rag.ragflow.document_ids`	list[string]	选填	-	检索RAGFlow的Document ID。
`rag.ragflow.similarity_threshold`	float	选填	0.2	相似度阈值, 低于阈值的分块会被过滤。
`rag.ragflow.top_n`	integer	选填	30	返回相似度最高的top_n个分块，其他分块会被过滤。
`rag.ragflow.vector_similarity_weight`	float	选填	0.3	向量余弦相似度权重，如果x表示向量余弦相似度，则`(1-x)`表示语义相似度权重。
`rag.ragflow.rerank_id`	integer	选填	-	RAG引擎中配置的Rerank模型的ID。

关于RAGFlow的知识库使用操作指引，请参见：Configure knowledge base。

关于RAGFlow的检索更详细参数说明，请参见：Retrieve chunks。

基础配置实例如下所示。

rag:
  rag_engine_type: "ragflow"
  ragflow:
    api_key: "xxxxxxxx"
    serviceFQDN: "xxxxxxxx"
    servicePort: 80
    dataset_ids:
      - "xxxxxxxx"
    document_ids:
      - "xxxxxxxx"
    similarity_threshold: 0.2
    top_n: 5
    vector_similarity_weight: 0.3
    rerank_id: "gte-rerank"

百炼知识库配置

当选择百炼知识库作为RAG引擎时（rag.rag_engine_type=bailian）, 请参考以下说明进行配置。

名称	数据类型	填写要求	默认值	描述
`rag.bailian.ak`	string	必填	-	调用百炼的access key，获取方式参考：成员管理。
`rag.bailian.sk`	string	必填	-	调用百炼的secret key，获取方式参考：成员管理。
`rag.bailian.serviceFQDN`	string	必填	-	百炼服务在AI网关的服务名。
`rag.bailian.workspace_id`	string	必填	-	阿里云百炼业务空间ID，获取方式参考：成员管理。
`rag.bailian.index_id`	string	必填	-	阿里云百炼知识库ID，获取方式参考：知识库API指南。
`rag.bailian.servicePort`	string	选填	443	百炼在AI网关的服务端口。
`rag.bailian.serviceHost`	string	选填	bailian.cn-beijing.aliyuncs.com	AI网关访问百炼时域名。
`rag.bailian.enable_reranking`	bool	选填	false	是否开启Rerank。
`rag.bailian.rerank_min_score`	float	选填	当前知识库配置的相似度阈值	仅开启Rerank时生效，Rerank后的相似度阈值，低于该阈值的分块会被过滤，取值范围：`[0.01 - 1.00]`。
`rag.bailian.rerank_top_n`	integer	选填	5	仅开启Rerank时生效，Rerank后的top_n返回分块, 取值范围：`[1 - 20]`。
`rag.bailian.rerank_model`	string	选填	gte-rerank-hybrid	仅开启Rerank时生效，Rerank模型，支持的模型包括：gte-rerank-hybrid、gte-rerank。
`rag.bailian.enable_rewrite`	bool	选填	false	是否开启会话改写。
`rag.bailian.rewrite_model`	string	选填	conv-rewrite-qwen-1.8b	仅开启会话改写时生效，会话改写模型名称，会基于会话上下文自动调整原始用户问题以提升检索效果，支持的模型包括：conv-rewrite-qwen-1.8b。
`rag.bailian.save_retriever_history`	bool	选填	false	是否保存历史检索召回数据。
`rag.bailian.dense_similarity_top_k`	integer	选填	100	向量检索TopK，通过生成输入文本的向量并在知识库中检索与其向量表示最相似的K个文本切片，取值范围：`[0 - 100]`。 dense_similarity_top_k和sparse_similarity_top_k二者之和小于等于200。
`rag.bailian.sparse_similarity_top_k`	integer	选填	100	关键词检索TopK，即在知识库中查找与输入文本的关键词精确匹配的切片。它可以帮助您过滤掉无关的文本切片，提供更准确的结果，取值范围：`[0 - 100]`。 dense_similarity_top_k和sparse_similarity_top_k二者之和小于等于200。

关于百炼平台的知识库使用操作指引，请参见：百炼知识库操作和使用指引。

关于百炼的检索更详细参数说明，请参见：Retrieve - 检索知识索引。

基础配置示例如下所示。

rag:
  rag_engine_type: bailian
  bailian:
    ak: xxxxxxxx
    sk: xxxxxxxx
    workspace_id: xxxxxxxx
    index_id: xxxxxxxx
    serviceFQDN: xxxxxxxx.dns
    enable_reranking: true
    rerank_min_score: 0.3
    rerank_top_n: 5
    save_retriever_history: false

操作指引

RAGFlow

创建Model API。在AI网关创建AI服务和文本生成场景Model API，确保可以通过Model API访问模型进行文本对话。
创建服务来源为固定地址的ragflow检索服务。在对应网关实例控制台的左侧导航栏，单击服务，并单击创建服务。表单配置如下所示。
如果是同VPC内容器部署的Ragflow的实例，也可以采用容器服务来源创建服务。
- 服务来源：选择固定地址。
- 服务名称：自定义服务名称，例如ragflow。
- 服务地址：格式为IP:端口，此处端口设置为80。
- TLS模式：保持默认关闭。
获取Ragflow服务FQDN和Port。
单击上述步骤创建的RagFlow服务，获取FQDN。RagFlow Port默认为80，用户可根据需要自行获取和设置。
获取待访问的RAGFlow信息。
1. 获取API Key。进入RAGFlow控制台，单击右上角用户头像->左侧选择API->API KEY，获取API Key。
2. 获取Dataset ID。前往RAGFlow的知识库页面，单击需要被检索的知识库，网页url中的id即为Dataset ID。
3. （可选）获取Document ID。前往RAGFlow的知识库页面，单击需要被检索的知识库，单击需要被检索的文档名，网页url中的doc_id即为Document ID。
在AI网关配置插件。在对应网关实例控制台，选择插件 > 安装插件 > AI > AI检索增强生成（加强版），单击安装并配置，配置到对应的生效范围。如下图所示。填入前序步骤获取的必需参数（api_key、serviceFQDN、dataset_ids、servicePort），可选参数可按需添加，如下图所示，单击启用后，配置即可生效。
调试并验证效果。在对应网关实例控制台，单击Model API，选择插件作用生效的API，并单击调试，验证添加RAG检索能力之后的模型返回结果。

百炼知识库

创建Model API。在AI网关创建AI服务和文本生成场景Model API，确保可以通过Model API访问模型进行文本对话。
创建服务来源为DNS域名的百炼检索服务。在对应网关实例控制台，选择服务 > 创建服务，表单配置如下所示。
- 服务来源：选择DNS域名。
- 服务名称：自定义服务名称，例如bailian-rag。
- 服务地址：格式为DNS域名:端口，此处端口设置为443。
- TLS模式：选择单向TLS。
获取百炼检索服务FQDN。单击上述步骤创建百炼检索服务，获取FQDN。
获取待访问的百炼知识库信息
1. 获取AK/SK。登录阿里云RAM访问控制台，参考创建AccessKey获取AccessKey和AccessKey Secret。
  说明
  为了您的数据安全，强烈建议您创建子账号并使用子账号AK/SK。需要保证您的子账号：
  - 具有AliyunBailianDataFullAccess或sfm:Retrieve的操作权限，参考为RAM用户授权为子账号授权。
  - 子账号已经被授权加入到百炼业务空间权限，参考成员管理。
2. 获取知识库命名空间ID。前往百炼应用页面，单击左下角查看知识库所在账号空间详情，获取业务空间ID。
3. 获取知识库ID。单击数据-知识库，选择待外挂检索的知识库，获取知识库ID。
在AI网关配置插件。在对应网关实例控制台，选择插件 > 安装插件 > AI > AI检索增强生成（加强版），单击安装并配置，配置到对应的生效范围。填入前序步骤获取的必需参数（ak、sk、serviceFQDN、workspace_id、index_id），可选参数可按需添加，如下图所示，单击启用后，配置即可生效。
调试并验证效果。在对应网关实例控制台，单击Model API，选择插件作用生效的API，并单击调试，验证添加RAG检索能力之后的模型返回结果。