docs: add knowledge retriever component development guidance

2026-10-30 12:25:29 +08:00 · 2025-11-28 18:38:37 +08:00
parent 3ef3efa8fe
commit 27df63e898
9 changed files with 539 additions and 2 deletions
@@ -5,6 +5,7 @@
 - 事件监听器（EventListener）：监听流水线执行期间的事件，对上下文或流水线进行修改。
 - 命令（Command）：由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。
 - 工具（Tool）：供 LangBot 内置的 Local Agent 在执行期间由 LLM 调用。
+- 知识检索器（KnowledgeRetriever）：为 LangBot 提供外部知识库检索能力，支持接入各类 RAG 系统。

 ## 添加组件

@@ -69,4 +70,5 @@ components:

 - [EventListener](./event-listener.md)
 - [Command](./command.md)
- [Tool](./tool.md)
+- [Tool](./tool.md)
+- [KnowledgeRetriever](./knowledge-retriever.md)
@@ -0,0 +1,265 @@
+# 组件：知识检索器
+
+知识检索器（Knowledge Retriever）组件允许插件为 LangBot 提供外部知识库检索能力。当用户在 LangBot 中创建外部知识库时，可以选择由插件提供的知识检索器来检索知识。
+
+<img width="600" src="/assets/image/zh/plugin/dev/components/knowledge_retriever_use.png" />
+
+## 添加知识检索器组件
+
+单个插件中能添加任意数量的知识检索器，请在插件目录执行命令`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://docs.langbot.app/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. 选择您的插件提供的知识检索器并填写配置
+
+<img width="600" src="/assets/image/zh/plugin/dev/components/knowledge_retriever_config.png" />
+
+保存后即可在 LangBot 流水线中选用该知识库。