85 lines
2.3 KiB
Python
85 lines
2.3 KiB
Python
"""KnowledgeBase 协议定义 - 外部知识库统一接口
|
||
|
||
独立于 Memory 接口，提供语义检索模型的知识库协议。
|
||
Memory 的 retrieve(key)/delete(key) 是精确 key-value 语义，
|
||
而 KnowledgeBase 的 query()/ingest() 更适合知识库的语义检索场景。
|
||
|
||
参见 KTD-7: KBAdapter 使用独立 KnowledgeBase 协议，不直接实现 Memory 接口。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass, field
|
||
from datetime import datetime, timezone
|
||
from typing import Any, Protocol, runtime_checkable
|
||
|
||
|
||
@dataclass
|
||
class Document:
|
||
"""知识库文档"""
|
||
|
||
doc_id: str
|
||
content: str
|
||
title: str = ""
|
||
source_id: str = ""
|
||
metadata: dict[str, Any] = field(default_factory=dict)
|
||
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
|
||
|
||
|
||
@dataclass
|
||
class QueryResult:
|
||
"""知识库检索结果"""
|
||
|
||
content: str
|
||
source_id: str
|
||
source_name: str
|
||
score: float
|
||
metadata: dict[str, Any] = field(default_factory=dict)
|
||
doc_id: str = ""
|
||
title: str = ""
|
||
|
||
|
||
@dataclass
|
||
class SourceInfo:
|
||
"""知识库信息源描述"""
|
||
|
||
source_id: str
|
||
source_name: str
|
||
source_type: str # e.g. "feishu", "confluence", "generic_http"
|
||
document_count: int = 0
|
||
last_updated: datetime | None = None
|
||
|
||
|
||
@runtime_checkable
|
||
class KnowledgeBase(Protocol):
|
||
"""知识库协议 - 统一的外部知识库接口
|
||
|
||
所有知识库适配器（飞书、Confluence、通用 HTTP 等）均实现此协议。
|
||
与 Memory 接口不同，KnowledgeBase 专注于语义检索模型：
|
||
- ingest() 批量写入文档
|
||
- query() 语义检索
|
||
- delete_by_id() 按文档 ID 删除
|
||
- list_sources() 列出可用信息源
|
||
- health_check() 检查连接状态
|
||
"""
|
||
|
||
async def ingest(self, documents: list[Document]) -> list[str]:
|
||
"""写入文档到知识库，返回文档 ID 列表"""
|
||
...
|
||
|
||
async def query(self, text: str, top_k: int = 5) -> list[QueryResult]:
|
||
"""语义检索知识库"""
|
||
...
|
||
|
||
async def delete_by_id(self, id: str) -> bool:
|
||
"""按文档 ID 删除"""
|
||
...
|
||
|
||
async def list_sources(self) -> list[SourceInfo]:
|
||
"""列出可用信息源"""
|
||
...
|
||
|
||
async def health_check(self) -> bool:
|
||
"""检查知识库连接状态"""
|
||
...
|