--- title: "组件：知识检索器" --- 知识检索器（Knowledge Retriever）组件允许插件为 LangBot 提供外部知识库检索能力。当用户在 LangBot 中创建外部知识库时，可以选择由插件提供的知识检索器来检索知识。 ## 添加知识检索器组件 单个插件中能添加任意数量的知识检索器，请在插件目录执行命令`lbp comp KnowledgeRetriever`，并根据提示输入知识检索器的配置。 ```bash ➜ FastGPTRetriever > lbp comp KnowledgeRetriever Generating component KnowledgeRetriever... KnowledgeRetriever name: fastgpt KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases Component KnowledgeRetriever generated successfully. 组件 KnowledgeRetriever 生成成功。 ``` 现在即会在`components/knowledge_retriever/`目录下生成`fastgpt.yaml`和`fastgpt.py`文件，`.yaml`定义了知识检索器的基础信息和配置参数，`.py`是该知识检索器的处理程序： ```bash ➜ FastGPTRetriever > tree ... ├── components │ ├── __init__.py │ └── knowledge_retriever │ ├── __init__.py │ ├── fastgpt.py │ └── fastgpt.yaml ... ``` ## 清单文件：知识检索器 ```yaml apiVersion: v1 # 请勿修改 kind: KnowledgeRetriever # 请勿修改 metadata: name: fastgpt # 知识检索器名称，用于标识该检索器 label: en_US: FastGPT Knowledge Base # 检索器显示名称，用于显示在 LangBot 的 UI 上，支持多语言 zh_Hans: FastGPT 知识库 ja_JP: FastGPT ナレッジベース description: en_US: 'Retrieve knowledge from FastGPT knowledge bases' # 检索器描述，用于显示在 LangBot 的 UI 上，支持多语言。可选 zh_Hans: '从 FastGPT 知识库中检索知识' ja_JP: 'FastGPT ナレッジベースから知識を取得' icon: assets/icon.svg # 检索器图标，会被展示在外部知识库配置页面 spec: config: # 检索器配置参数，用户在创建外部知识库时需要填写这些参数 - name: api_base_url # 参数名称 type: string # 参数类型：string, number, boolean, select label: en_US: API Base URL zh_Hans: API 基础地址 ja_JP: API ベース URL description: en_US: 'Base URL for FastGPT API' zh_Hans: 'FastGPT API 基础地址' ja_JP: 'FastGPT API ベース URL' default: 'http://localhost:3000' # 参数默认值 required: true # 是否必填 - name: api_key type: string label: en_US: FastGPT API Key zh_Hans: FastGPT API Key ja_JP: FastGPT API キー description: en_US: 'API key from your FastGPT instance' zh_Hans: '从您的 FastGPT 实例获取的 API Key' ja_JP: 'FastGPT インスタンスから取得した API Key' default: '' required: true - name: search_mode # select 类型参数示例 type: select label: en_US: Search Mode zh_Hans: 搜索模式 ja_JP: 検索モード description: en_US: 'The search method to use' zh_Hans: '使用的搜索方法' ja_JP: '使用する検索方法' default: 'embedding' options: # select 类型参数需要定义选项列表 - name: 'embedding' label: en_US: 'Embedding Search' zh_Hans: '向量搜索' ja_JP: '埋め込み検索' - name: 'fullTextRecall' label: en_US: 'Full-Text Recall' zh_Hans: '全文检索' ja_JP: '全文検索' - name: using_rerank # boolean 类型参数示例 type: boolean label: en_US: Use Re-ranking zh_Hans: 使用重排序 ja_JP: リランキングを使用 description: en_US: 'Whether to use re-ranking' zh_Hans: '是否使用重排序' ja_JP: 'リランキングを使用するかどうか' default: false required: false execution: python: path: fastgpt.py # 检索器处理程序，请勿修改 attr: FastGPT # 检索器处理程序的类名，与 fastgpt.py 中的类名一致 ``` 配置项格式可参考：[插件清单配置项格式](/zh/plugin/dev/basic-info) ## 插件处理 默认会生成如下代码(`components/knowledge_retriever/<检索器名称>.py`)，您需要在`FastGPT`类的`retrieve`方法中实现知识检索逻辑。完整代码可在[langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo)中找到。 ```python # Auto generated by LangBot Plugin SDK. # Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details. ... class FastGPT(KnowledgeRetriever): async def retrieve(self, context: RetrievalContext) -> list[RetrievalResultEntry]: """Retrieve knowledge from FastGPT knowledge base""" # 1. 获取配置参数 api_base_url = self.config.get('api_base_url', 'http://localhost:3000') api_key = self.config.get('api_key') dataset_id = self.config.get('dataset_id') search_mode = self.config.get('search_mode', 'embedding') using_rerank = self.config.get('using_rerank', False) # 2. 参数验证 if not api_key or not dataset_id: logger.error("Missing required configuration: api_key or dataset_id") return [] # 3. 构建 API 请求 url = f"{api_base_url.rstrip('/')}/api/core/dataset/searchTest" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } payload = { "datasetId": dataset_id, "text": context.query, # 从 RetrievalContext 获取查询文本 "searchMode": search_mode, "usingReRank": using_rerank, } try: # 4. 调用外部 API async with httpx.AsyncClient() as client: response = await client.post(url, json=payload, headers=headers, timeout=30.0) response.raise_for_status() result = response.json() # 5. 解析响应并转换为 RetrievalResultEntry results = [] for record in result.get('data', []): # 合并主要数据和辅助数据作为内容 content_text = '\n'.join([ record.get('q', ''), record.get('a', '') ]).strip() # 创建检索结果条目 entry = RetrievalResultEntry( id=record.get('id', ''), content=[ContentElement.from_text(content_text)], metadata={ 'dataset_id': record.get('datasetId', ''), 'source_name': record.get('sourceName', ''), 'score': record.get('score', 0.0), }, # 将相似度分数转换为距离（分数越高，距离越小） distance=1.0 - float(record.get('score', 0.0)), ) results.append(entry) logger.info(f"Retrieved {len(results)} chunks from FastGPT dataset {dataset_id}") return results except httpx.HTTPStatusError as e: logger.error(f"HTTP error from FastGPT API: {e.response.status_code} - {e.response.text}") return [] except httpx.RequestError as e: logger.error(f"Request error when calling FastGPT API: {str(e)}") return [] except Exception as e: traceback.print_exc() logger.error(f"Unexpected error during retrieval: {str(e)}") return [] ``` ### 检索上下文 `RetrievalContext` 包含本次检索的上下文信息： ```python class RetrievalContext(pydantic.BaseModel): """知识检索上下文""" query: str """查询文本，用户的检索问题""" ``` ### 检索结果 检索结果需要转换为 `RetrievalResultEntry` 对象列表，每个对象代表一个检索到的知识块： ```python class RetrievalResultEntry(pydantic.BaseModel): """单个检索结果条目""" id: str """结果 ID，唯一标识此条目""" content: list[ContentElement] """结果内容，使用 ContentElement.from_text() 创建文本内容""" metadata: dict[str, Any] """结果元数据，可以包含任意键值对，如来源、分数等""" distance: float """距离分数，表示与查询的相关度（越小越相关） 通常通过 1.0 - similarity_score 计算""" ``` ### 获取配置参数 通过 `self.config.get(参数名, 默认值)` 获取用户配置的参数值： ```python # 获取字符串参数 api_base_url = self.config.get('api_base_url', 'http://localhost:3000') # 获取数字参数 limit = self.config.get('limit', 5000) similarity = self.config.get('similarity', 0.0) # 获取布尔参数 using_rerank = self.config.get('using_rerank', False) # 获取 select 参数 search_mode = self.config.get('search_mode', 'embedding') ``` ## 测试检索器 创建完成后，在插件目录执行命令 `lbp run`，启动调试。然后在 LangBot 中： 1. 进入"知识库"页面 2. 添加外部知识库 3. 选择您的插件提供的知识检索器并填写配置 保存后即可在 LangBot 流水线中选用该知识库。