From 94337e6c8eaf80b61efea21f7e13655ed12d44d5 Mon Sep 17 00:00:00 2001 From: huanghuoguoguo <1051233107@qq.com> Date: Thu, 12 Mar 2026 22:15:48 +0800 Subject: [PATCH] feat: add list kbengine and parser api (#89) --- en/plugin/dev/apis/common.mdx | 75 ++++++++++++++++++++++++++++- en/plugin/dev/components/parser.mdx | 16 ++++-- ja/plugin/dev/apis/common.mdx | 75 ++++++++++++++++++++++++++++- ja/plugin/dev/components/parser.mdx | 16 ++++-- zh/plugin/dev/apis/common.mdx | 75 ++++++++++++++++++++++++++++- zh/plugin/dev/components/parser.mdx | 16 ++++-- 6 files changed, 261 insertions(+), 12 deletions(-) diff --git a/en/plugin/dev/apis/common.mdx b/en/plugin/dev/apis/common.mdx index 80d84f899..d228ce2c6 100644 --- a/en/plugin/dev/apis/common.mdx +++ b/en/plugin/dev/apis/common.mdx @@ -82,6 +82,66 @@ async def get_query_vars(self) -> dict[str, Any]: query_vars = await event_context.get_query_vars() ``` +### List Knowledge Bases Configured for the Current Pipeline + +Get the knowledge bases configured in the pipeline used by the current request. + +```python +async def list_pipeline_knowledge_bases(self) -> list[dict[str, Any]]: + """List knowledge bases configured for the current pipeline""" + +# Usage example +knowledge_bases = await event_context.list_pipeline_knowledge_bases() + +# Return example +[ + { + "uuid": "kb_uuid", + "name": "Product Docs", + "description": "Internal product documentation", + } +] +``` + +This only returns knowledge bases bound in the current pipeline's `Local Agent` configuration. If the pipeline has no knowledge base configured, or is not using `Local Agent`, an empty list is returned. + +### Retrieve Knowledge from the Current Pipeline Scope + +Run retrieval against the knowledge bases that are allowed for the current request's pipeline. + +```python +async def retrieve_knowledge( + self, + kb_id: str, + query_text: str, + top_k: int = 5, + filters: dict[str, Any] | None = None, +) -> list[dict[str, Any]]: + """Retrieve relevant documents from a knowledge base""" + +# Usage example +knowledge_bases = await event_context.list_pipeline_knowledge_bases() +results = await event_context.retrieve_knowledge( + kb_id=knowledge_bases[0]["uuid"], + query_text="How do I configure the enterprise knowledge base?", + top_k=3, + filters={"document_type": {"$eq": "manual"}}, +) + +# Return example +[ + { + "id": "chunk_0", + "content": [{"type": "text", "text": "Knowledge base configuration guide"}], + "metadata": {"document_id": "doc_001"}, + "distance": 0.12, + "score": 0.88, + } +] +``` + +`kb_id` must come from `list_pipeline_knowledge_bases` and must belong to a knowledge base configured for the current pipeline. Otherwise, LangBot returns an error. + ## LangBot API These APIs can be called in any plugin component. Access methods: @@ -213,6 +273,19 @@ llm_message = await self.plugin.invoke_llm( ) ``` +### List Available Parsers + +List Parser plugins currently available on the host, optionally filtered by MIME type. + +```python +async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]: + """List available Parser plugins""" + +# Usage example +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types +``` + ### Set Plugin Persistent Data Persistently store plugin data. Data stored through this interface can only be accessed by this plugin. Values need to be converted to bytes manually. @@ -495,4 +568,4 @@ async def get_knowledge_file_stream(self, storage_path: str) -> bytes: # Usage example file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path) -``` \ No newline at end of file +``` diff --git a/en/plugin/dev/components/parser.mdx b/en/plugin/dev/components/parser.mdx index de19c9d50..04f1ec0f2 100644 --- a/en/plugin/dev/components/parser.mdx +++ b/en/plugin/dev/components/parser.mdx @@ -176,12 +176,22 @@ async def ingest(self, context: IngestionContext) -> IngestionResult: ## Cross-Plugin Parser Invocation -KnowledgeEngine plugins can invoke parsers provided by other plugins via `self.plugin.invoke_parser`: +Before invoking a parser from another plugin, you can use `self.plugin.list_parsers` to discover the parsers currently available on the host: ```python +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types +``` + +If the list is empty, no connected Parser plugin currently supports that MIME type. + +After obtaining `plugin_author` and `plugin_name`, you can call `self.plugin.invoke_parser`: + +```python +parser = parsers[0] result = await self.plugin.invoke_parser( - plugin_author="author_name", - plugin_name="plugin_name", + plugin_author=parser["plugin_author"], + plugin_name=parser["plugin_name"], storage_path=context.file_object.storage_path, mime_type=context.file_object.metadata.mime_type, filename=context.file_object.metadata.filename, diff --git a/ja/plugin/dev/apis/common.mdx b/ja/plugin/dev/apis/common.mdx index c61ab1bb0..a681f30ab 100644 --- a/ja/plugin/dev/apis/common.mdx +++ b/ja/plugin/dev/apis/common.mdx @@ -82,6 +82,66 @@ async def get_query_vars(self) -> dict[str, Any]: query_vars = await event_context.get_query_vars() ``` +### 現在のパイプラインに設定されたナレッジベース一覧の取得 + +現在のリクエストで使用されているパイプラインに設定されたナレッジベース一覧を取得します。 + +```python +async def list_pipeline_knowledge_bases(self) -> list[dict[str, Any]]: + """List knowledge bases configured for the current pipeline""" + +# 使用例 +knowledge_bases = await event_context.list_pipeline_knowledge_bases() + +# 返却例 +[ + { + "uuid": "kb_uuid", + "name": "Product Docs", + "description": "社内製品ドキュメント", + } +] +``` + +返されるのは、現在のパイプラインの `Local Agent` 設定に紐づいたナレッジベースだけです。ナレッジベースが未設定、または `Local Agent` を使っていない場合は空配列になります。 + +### 現在のパイプライン範囲でナレッジを検索 + +現在のリクエストのパイプラインで許可されているナレッジベースの範囲内で検索を実行します。 + +```python +async def retrieve_knowledge( + self, + kb_id: str, + query_text: str, + top_k: int = 5, + filters: dict[str, Any] | None = None, +) -> list[dict[str, Any]]: + """Retrieve relevant documents from a knowledge base""" + +# 使用例 +knowledge_bases = await event_context.list_pipeline_knowledge_bases() +results = await event_context.retrieve_knowledge( + kb_id=knowledge_bases[0]["uuid"], + query_text="エンタープライズ向けナレッジベースの設定方法は？", + top_k=3, + filters={"document_type": {"$eq": "manual"}}, +) + +# 返却例 +[ + { + "id": "chunk_0", + "content": [{"type": "text", "text": "ナレッジベース設定ガイド"}], + "metadata": {"document_id": "doc_001"}, + "distance": 0.12, + "score": 0.88, + } +] +``` + +`kb_id` は `list_pipeline_knowledge_bases` の返却値から取得し、現在のパイプラインに設定されたナレッジベースである必要があります。そうでない場合、LangBot はエラーを返します。 + ## LangBot API これらのAPIは、任意のプラグインコンポーネントで呼び出すことができます。アクセス方法: @@ -213,6 +273,19 @@ llm_message = await self.plugin.invoke_llm( ) ``` +### 利用可能な Parser の一覧取得 + +ホスト上で現在利用可能な Parser プラグインを列挙します。MIME タイプで絞り込むこともできます。 + +```python +async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]: + """List available Parser plugins""" + +# 使用例 +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# 各要素には plugin_id、plugin_author、plugin_name、name、description、supported_mime_types が含まれます +``` + ### プラグイン永続データの設定 プラグインデータを永続的に保存します。このインターフェースを通じて保存されたデータは、このプラグインのみがアクセスできます。値は手動でbytesに変換する必要があります。 @@ -495,4 +568,4 @@ async def get_knowledge_file_stream(self, storage_path: str) -> bytes: # 使用例 file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path) -``` \ No newline at end of file +``` diff --git a/ja/plugin/dev/components/parser.mdx b/ja/plugin/dev/components/parser.mdx index 247894ada..85fa14cea 100644 --- a/ja/plugin/dev/components/parser.mdx +++ b/ja/plugin/dev/components/parser.mdx @@ -177,12 +177,22 @@ async def ingest(self, context: IngestionContext) -> IngestionResult: ## クロスプラグインパーサー呼び出し -KnowledgeEngineプラグインは`self.plugin.invoke_parser`を通じて、他のプラグインが提供するパーサーを呼び出すことができます: +他のプラグインが提供するパーサーを呼び出す前に、`self.plugin.list_parsers` を使ってホスト上で現在利用可能なパーサーを列挙できます: ```python +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# 各要素には plugin_id、plugin_author、plugin_name、name、description、supported_mime_types が含まれます +``` + +空配列が返る場合、その MIME タイプに対応する接続済みの Parser プラグインは現在存在しません。 + +`plugin_author` と `plugin_name` を取得したら、`self.plugin.invoke_parser` で対象のパーサーを呼び出せます: + +```python +parser = parsers[0] result = await self.plugin.invoke_parser( - plugin_author="author_name", - plugin_name="plugin_name", + plugin_author=parser["plugin_author"], + plugin_name=parser["plugin_name"], storage_path=context.file_object.storage_path, mime_type=context.file_object.metadata.mime_type, filename=context.file_object.metadata.filename, diff --git a/zh/plugin/dev/apis/common.mdx b/zh/plugin/dev/apis/common.mdx index c3db5e186..1429c3041 100644 --- a/zh/plugin/dev/apis/common.mdx +++ b/zh/plugin/dev/apis/common.mdx @@ -82,6 +82,66 @@ async def get_query_vars(self) -> dict[str, Any]: query_vars = await event_context.get_query_vars() ``` +### 获取当前流水线配置的知识库列表 + +获取当前请求所使用流水线中配置的知识库列表。 + +```python +async def list_pipeline_knowledge_bases(self) -> list[dict[str, Any]]: + """List knowledge bases configured for the current pipeline""" + +# 调用示例 +knowledge_bases = await event_context.list_pipeline_knowledge_bases() + +# 返回示例 +[ + { + "uuid": "kb_uuid", + "name": "Product Docs", + "description": "内部产品文档", + } +] +``` + +仅返回当前请求对应流水线在 `Local Agent` 配置中绑定的知识库。若当前流水线未配置知识库，或未使用 `Local Agent`，则返回空列表。 + +### 检索当前流水线内的知识库 + +在当前请求所属流水线允许访问的知识库范围内执行检索。 + +```python +async def retrieve_knowledge( + self, + kb_id: str, + query_text: str, + top_k: int = 5, + filters: dict[str, Any] | None = None, +) -> list[dict[str, Any]]: + """Retrieve relevant documents from a knowledge base""" + +# 调用示例 +knowledge_bases = await event_context.list_pipeline_knowledge_bases() +results = await event_context.retrieve_knowledge( + kb_id=knowledge_bases[0]["uuid"], + query_text="如何配置企业知识库？", + top_k=3, + filters={"document_type": {"$eq": "manual"}}, +) + +# 返回示例 +[ + { + "id": "chunk_0", + "content": [{"type": "text", "text": "知识库配置说明"}], + "metadata": {"document_id": "doc_001"}, + "distance": 0.12, + "score": 0.88, + } +] +``` + +`kb_id` 必须来自 `list_pipeline_knowledge_bases` 的返回结果，且必须属于当前流水线已配置的知识库，否则 LangBot 会返回错误。 + ## LangBot API 这些 API 可在插件任何组件中调用。访问方式如下： @@ -213,6 +273,19 @@ llm_message = await self.plugin.invoke_llm( ) ``` +### 列出可用解析器 + +列出宿主当前可用的 Parser 插件，可按 MIME 类型过滤。 + +```python +async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]: + """List available Parser plugins""" + +# 调用示例 +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# 返回的每项包含 plugin_id、plugin_author、plugin_name、name、description、supported_mime_types +``` + ### 设置插件持久化数据 持久化存储插件数据。通过这个接口存储的数据，仅可被该插件访问。值需要自行转换为字节。 @@ -495,4 +568,4 @@ async def get_knowledge_file_stream(self, storage_path: str) -> bytes: # 调用示例 file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path) -``` \ No newline at end of file +``` diff --git a/zh/plugin/dev/components/parser.mdx b/zh/plugin/dev/components/parser.mdx index 47d4a1d32..83f413fc8 100644 --- a/zh/plugin/dev/components/parser.mdx +++ b/zh/plugin/dev/components/parser.mdx @@ -177,12 +177,22 @@ async def ingest(self, context: IngestionContext) -> IngestionResult: ## 跨插件调用解析器 -KnowledgeEngine 插件可以通过 `self.plugin.invoke_parser` 方法调用其他插件提供的解析器： +在调用其他插件提供的解析器之前，可以先通过 `self.plugin.list_parsers` 枚举当前可用的解析器： ```python +parsers = await self.plugin.list_parsers(mime_type="application/pdf") +# 返回的每项包含 plugin_id、plugin_author、plugin_name、name、description、supported_mime_types +``` + +若返回空列表，说明宿主当前没有已连接且支持该 MIME 类型的 Parser 插件。 + +拿到 `plugin_author` 和 `plugin_name` 后，即可通过 `self.plugin.invoke_parser` 调用对应解析器： + +```python +parser = parsers[0] result = await self.plugin.invoke_parser( - plugin_author="author_name", - plugin_name="plugin_name", + plugin_author=parser["plugin_author"], + plugin_name=parser["plugin_name"], storage_path=context.file_object.storage_path, mime_type=context.file_object.metadata.mime_type, filename=context.file_object.metadata.filename,