使用AI檢索增強產生（加強版）外掛程式對接RAGFlow與百鍊知識庫-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的執行個體，也可以採用Container Service來源建立服務。
- 服務來源：選擇固定地址。
- 服務名稱：自訂服務名稱，例如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檢索能力之後的模型返回結果。