mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-30 04:15:45 +08:00
docs: add knowledge retriever component development guidance
This commit is contained in:
Junyan Qin
@@ -205,6 +205,7 @@ export default defineConfig({
|
||||
{ text: "组件：事件监听器", link: "/zh/plugin/dev/components/event-listener" },
|
||||
{ text: "组件：命令", link: "/zh/plugin/dev/components/command" },
|
||||
{ text: "组件：工具", link: "/zh/plugin/dev/components/tool" },
|
||||
{ text: "组件：知识检索器", link: "/zh/plugin/dev/components/knowledge-retriever" },
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -477,6 +478,7 @@ export default defineConfig({
|
||||
{ text: "Component: Event Listener", link: "/en/plugin/dev/components/event-listener" },
|
||||
{ text: "Component: Command", link: "/en/plugin/dev/components/command" },
|
||||
{ text: "Component: Tool", link: "/en/plugin/dev/components/tool" },
|
||||
{ text: "Component: Knowledge Retriever", link: "/en/plugin/dev/components/knowledge-retriever" },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
@@ -5,6 +5,7 @@ Plugins consist of one or more components that provide different functionalities
|
||||
- Event Listeners (EventListener): Listen to events during pipeline execution and modify context or pipelines.
|
||||
- Commands (Command): Triggered by user command messages starting with `!` (or other configured prefixes).
|
||||
- Tools (Tool): Called by LLMs during execution of LangBot's built-in Local Agent.
|
||||
- Knowledge Retrievers (KnowledgeRetriever): Provide external knowledge base retrieval capabilities for LangBot, supporting integration with various RAG systems.
|
||||
|
||||
## Adding Components
|
||||
|
||||
@@ -68,4 +69,5 @@ For detailed usage of each component, please refer to:
|
||||
|
||||
- [EventListener](./event-listener.md)
|
||||
- [Command](./command.md)
|
||||
- [Tool](./tool.md)
|
||||
- [Tool](./tool.md)
|
||||
- [KnowledgeRetriever](./knowledge-retriever.md)
|
||||
@@ -0,0 +1,264 @@
|
||||
# Component: Knowledge Retriever
|
||||
|
||||
The Knowledge Retriever component allows plugins to provide external knowledge base retrieval capabilities for LangBot. When users create an external knowledge base in LangBot, they can choose a knowledge retriever provided by a plugin to retrieve knowledge.
|
||||
|
||||
<img width="600" src="/assets/image/zh/plugin/dev/components/knowledge_retriever_use.png" />
|
||||
|
||||
## Adding a Knowledge Retriever Component
|
||||
|
||||
A single plugin can add any number of knowledge retrievers. Execute the command `lbp comp KnowledgeRetriever` in the plugin directory and follow the prompts to enter the knowledge retriever configuration.
|
||||
|
||||
```bash
|
||||
➜ FastGPTRetriever > lbp comp KnowledgeRetriever
|
||||
Generating component KnowledgeRetriever...
|
||||
KnowledgeRetriever name: fastgpt
|
||||
KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases
|
||||
Component KnowledgeRetriever generated successfully.
|
||||
```
|
||||
|
||||
This will generate `fastgpt.yaml` and `fastgpt.py` files in the `components/knowledge_retriever/` directory. The `.yaml` file defines the basic information and configuration parameters of the knowledge retriever, and the `.py` file is the handler for this retriever:
|
||||
|
||||
```bash
|
||||
➜ FastGPTRetriever > tree
|
||||
...
|
||||
├── components
|
||||
│ ├── __init__.py
|
||||
│ └── knowledge_retriever
|
||||
│ ├── __init__.py
|
||||
│ ├── fastgpt.py
|
||||
│ └── fastgpt.yaml
|
||||
...
|
||||
```
|
||||
|
||||
## Manifest File: Knowledge Retriever
|
||||
|
||||
```yaml
|
||||
apiVersion: v1 # Do not modify
|
||||
kind: KnowledgeRetriever # Do not modify
|
||||
metadata:
|
||||
name: fastgpt # Knowledge retriever name, used to identify this retriever
|
||||
label:
|
||||
en_US: FastGPT Knowledge Base # Retriever display name, shown in LangBot's UI, supports multiple languages
|
||||
zh_Hans: FastGPT 知识库
|
||||
ja_JP: FastGPT ナレッジベース
|
||||
description:
|
||||
en_US: 'Retrieve knowledge from FastGPT knowledge bases' # Retriever description, shown in LangBot's UI, supports multiple languages. Optional
|
||||
zh_Hans: '从 FastGPT 知识库中检索知识'
|
||||
ja_JP: 'FastGPT ナレッジベースから知識を取得'
|
||||
icon: assets/icon.svg # Retriever icon, displayed on the external knowledge base configuration page
|
||||
spec:
|
||||
config: # Retriever configuration parameters, users need to fill in these parameters when creating an external knowledge base
|
||||
- name: api_base_url # Parameter name
|
||||
type: string # Parameter type: 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' # Default parameter value
|
||||
required: true # Whether required
|
||||
- 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 # Example of select type parameter
|
||||
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 type parameters need to define an option list
|
||||
- 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 # Example of boolean type parameter
|
||||
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 # Retriever handler, do not modify
|
||||
attr: FastGPT # Class name of the retriever handler, consistent with the class name in fastgpt.py
|
||||
```
|
||||
|
||||
For configuration item format reference, see: [Plugin Manifest Configuration Format](/en/plugin/dev/basic-info)
|
||||
|
||||
## Plugin Handler
|
||||
|
||||
The following code will be generated by default (components/knowledge_retriever/<retriever_name>.py). You need to implement the knowledge retrieval logic in the `retrieve` method of the `FastGPT` class. Complete code can be found in [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. Get configuration parameters
|
||||
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. Parameter validation
|
||||
if not api_key or not dataset_id:
|
||||
logger.error("Missing required configuration: api_key or dataset_id")
|
||||
return []
|
||||
|
||||
# 3. Build API request
|
||||
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, # Get query text from RetrievalContext
|
||||
"searchMode": search_mode,
|
||||
"usingReRank": using_rerank,
|
||||
}
|
||||
|
||||
try:
|
||||
# 4. Call external 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. Parse response and convert to RetrievalResultEntry
|
||||
results = []
|
||||
for record in result.get('data', []):
|
||||
# Combine main data and auxiliary data as content
|
||||
content_text = '\n'.join([
|
||||
record.get('q', ''),
|
||||
record.get('a', '')
|
||||
]).strip()
|
||||
|
||||
# Create retrieval result entry
|
||||
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),
|
||||
},
|
||||
# Convert similarity score to distance (higher score = smaller distance)
|
||||
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 []
|
||||
```
|
||||
|
||||
### Retrieval Context
|
||||
|
||||
`RetrievalContext` contains context information for this retrieval:
|
||||
|
||||
```python
|
||||
class RetrievalContext(pydantic.BaseModel):
|
||||
"""Knowledge retrieval context"""
|
||||
|
||||
query: str
|
||||
"""Query text, the user's retrieval question"""
|
||||
```
|
||||
|
||||
### Retrieval Results
|
||||
|
||||
Retrieval results need to be converted to a list of `RetrievalResultEntry` objects, each representing a retrieved knowledge chunk:
|
||||
|
||||
```python
|
||||
class RetrievalResultEntry(pydantic.BaseModel):
|
||||
"""Single retrieval result entry"""
|
||||
|
||||
id: str
|
||||
"""Result ID, uniquely identifies this entry"""
|
||||
|
||||
content: list[ContentElement]
|
||||
"""Result content, create text content using ContentElement.from_text()"""
|
||||
|
||||
metadata: dict[str, Any]
|
||||
"""Result metadata, can contain any key-value pairs, such as source, score, etc."""
|
||||
|
||||
distance: float
|
||||
"""Distance score, indicates relevance to the query (smaller is more relevant)
|
||||
Usually calculated as 1.0 - similarity_score"""
|
||||
```
|
||||
|
||||
### Getting Configuration Parameters
|
||||
|
||||
Get user-configured parameter values using `self.config.get(parameter_name, default_value)`:
|
||||
|
||||
```python
|
||||
# Get string parameter
|
||||
api_base_url = self.config.get('api_base_url', 'http://localhost:3000')
|
||||
|
||||
# Get number parameters
|
||||
limit = self.config.get('limit', 5000)
|
||||
similarity = self.config.get('similarity', 0.0)
|
||||
|
||||
# Get boolean parameter
|
||||
using_rerank = self.config.get('using_rerank', False)
|
||||
|
||||
# Get select parameter
|
||||
search_mode = self.config.get('search_mode', 'embedding')
|
||||
```
|
||||
|
||||
## Testing the Retriever
|
||||
|
||||
After creation, execute the command `lbp run` in the plugin directory to start debugging. Then in LangBot:
|
||||
|
||||
1. Go to the "Knowledge Base" page
|
||||
2. Add an external knowledge base
|
||||
3. Select the knowledge retriever provided by your plugin and fill in the configuration
|
||||
|
||||
<img width="600" src="/assets/image/zh/plugin/dev/components/knowledge_retriever_config.png" />
|
||||
|
||||
After saving, you can select this knowledge base in the LangBot pipeline.
|
||||
@@ -13,6 +13,7 @@ Plugins can provide the following components based on their specific functionali
|
||||
- Event Handlers: Listen to events during pipeline execution and modify context or pipelines.
|
||||
- Commands: Triggered by user command messages starting with `!` (or other configured prefixes).
|
||||
- Tools: Called by LLMs during execution of LangBot's built-in Local Agent.
|
||||
- Knowledge Retrievers: Used to retrieve relevant knowledge from external knowledge bases.
|
||||
|
||||
More component types will be supported for plugin implementation in the future.
|
||||
|
||||
|
||||
@@ -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 流水线中选用该知识库。
|
||||
@@ -13,6 +13,7 @@ LangBot 内部由多种组件组成，如大模型工具、命令、消息平台
|
||||
- 事件处理器：监听流水线执行期间的事件，对上下文或流水线进行修改。
|
||||
- 命令：由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。
|
||||
- 工具：供 LangBot 内置的 Local Agent 在执行期间由 LLM 调用。
|
||||
- 知识检索器：用于从外部知识库中检索相关知识。
|
||||
|
||||
后续还将支持更多组件的插件化。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user