用途
ragskill 是一个基于 FastAPI 知识库服务实现的 RAG（检索增强生成）知识管理与检索技能，用于为 Agent 或机器人提供知识库问答能力，覆盖文档入库、管理、检索等流程。
主要能力
包含的功能如下：
- 支持本地文件上传（txt/md/pdf/docx 等），自动解析文本与图片
- 支持图片提取、VLM 图文理解、描述向量化入库
- 支持单文件删除、全库清空
- 支持查询已上传文件列表
- 支持查询文件解析后的文本/图片片段内容
- 支持语义向量检索 + BM25 全文检索混合召回
- 支持相似度阈值、返回条数配置
前置要求
在使用该技能前，需确保已配置 RAG 服务端的 RAG_SERVER_ADDRESS 环境变量：
- RAG_SERVER_ADDRESS：RAG 知识管理服务 fastapi 服务 url，例如：http://127.0.0.1:8000
使用方式
当前 skill 目录下的 example.py 文件描述 RAG 服务各接口客户端请求样例代码，核心为 RAGClient 类，其各方法输入输出如下：
query
- server interface: /query
- request method: POST
- description: 根据用户问题从知识库中获取知识信息总结最终答案
- Input:
- query: str（用户问题）
- top_k: int = 3（返回条数）
- score_threshold: float = 0.5（相似度阈值）
- Output: str
retrieve_similar_docs
- server interface: /retrieval
- request method: POST
- description: 根据用户问题从知识库中检索召回 top_k 个语义最相似的知识片段
- Input:
- query: str（用户问题）
- top_k: int = 3（返回条数）
- score_threshold: float = 0.5（相似度阈值）
- Output: List[Dict]（content, score, metadata）
upload_file
- server interface: /upload_file
- request method: POST
- description: 上传文档到 RAG 知识库中
- Input: file_path: str（本地文件路径）
- Output: Dict（上传结果、状态信息）
- Exception: FileNotFoundError, HTTPError
delete_file
- server interface: /delete_file
- request method: POST
- description: 删除指定的文件名
- Input:
- file_name: str（知识库中文件名）
- confirm: bool = False（确认删除）
- Output: Dict（删除结果）
delete_all_files
- server interface: /delete_all_files
- request method: DELETE
- description: 删除 RAG 知识库中所有文件
- Input: confirm: bool = False（确认删除）
- Output: Dict（清空结果）
list_files
- server interface: /list_files
- request method: GET
- description: 查看 RAG 知识库中所有的文件名
- Input: None
- Output: List[str]（文件名称列表）
query_file_content
- server interface: /query_file_content
- request method: POST
- description: 查看 RAG 知识库中指定文件名的内容
- Input: file_name: str
- Output: List[Dict[str, Any]]（文本片段+元数据）
Usage Example
from example import RAGClient
client = RAGClient(base_url="http://127.0.0.1:9098")
# 上传文件
await client.upload_file("/path/test.pdf")
# 检索知识
docs = await client.retrieval("什么是RAG？")
# 查询文件列表
files = await client.list_files()
# 删除文件
await client.delete_file("test.pdf", confirm=True)
适用场景
适用于需要为 Agent 或机器人构建知识问答能力的场景，例如将本地 PDF、DOCX、TXT、MD 文档及图片内容入库，并通过语义向量检索与 BM25 全文检索混合召回获取相关知识，用于问答总结或片段召回。
限制
使用前必须配置 RAG_SERVER_ADDRESS 环境变量指向 RAG 知识管理服务。关于收费、价格、具体部署方式及其他平台支持信息暂未提供。