# RAGSkill

> 基于FastAPI知识库服务实现的RAG知识管理与检索技能，支持文档上传、解析、入库、删除、列表查询、内容检索、全文检索等能力，兼容PDF/DOCX/TXT/MD等格式，支持图片解析与多粒度描述入库，可直接对接Agent/机器人进行知识问答。

- Skill: `ascend/ragskill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ascend/ragskill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ascend/ragskill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ascend (https://skillmd.com/u/ascend)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ascend/ragskill

---

-

# 包含的功能
- 支持本地文件上传（txt/md/pdf/docx等），自动解析文本与图片
- 支持图片提取、VLM图文理解、描述向量化入库
- 支持单文件删除、全库清空
- 支持查询已上传文件列表
- 支持查询文件解析后的文本/图片片段内容
- 支持语义向量检索 + BM25全文检索混合召回
- 支持相似度阈值、返回条数配置

# 前置要求
在使用该SKILL前，需确保已配置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
```python
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)
```