hatim-be-ragie-rag

基于 Ragie.ai 的确定性 RAG 摄取、检索与有依据问答工作流。

---
name: ragie-rag
description: |
  使用 Ragie.ai 执行检索增强生成 (RAG)。
  每当用户想要执行以下操作时就可以使用此技能：
  - 搜索他们的知识库
  - 询问有关上传文件的问题
  - 上传文件至Ragie
  - 从 Ragie 检索上下文
  - 使用存储的文档进行接地应答
  - 列出、检查状态或删除 Ragie 文档
  该技能管理整个 Ragie.ai API 生命周期，包括摄取、
  检索和接地答案构建。
metadata:
{
    "openclaw":
      {
        "requires":
          {
            "bins": ["python3"],
            "env": ["RAGIE_API_KEY"],
            "python": ["requests", "python-dotenv"]
          },
        "credentials":
          {
            "primary": "RAGIE_API_KEY",
            "description": "API key from https://app.ragie.ai"
          }
      }
  }
---

## 概述（中文）

基于 Ragie.ai 的确定性 RAG 摄取、检索与有依据问答工作流。

## 技能正文

# Ragie.ai RAG 技能（OpenClaw 优化版）

此技能以 Ragie.ai 作为 RAG 后端，实现有依据的问答。

Ragie 负责：
- 文档分块
- 嵌入
- 向量索引
- 检索
- 可选的重排序

代理负责：
- 决定何时摄取
- 触发检索
- 构造有依据的提示词
- 产出最终答案

---

# 核心原则

1. 永不在未检索的情况下回答。
2. 永不臆造检索到的分块中不存在的信息。
3. 引用具体事实时，始终标注 `document_name`。
4. 如果检索返回零个相关分块，明确说明：
   > "I don't have that information in the current knowledge base."
5. 不要在最终答案中暴露 API 密钥或原始 API 负载。

---

# 确定性工作流

## 情形 A —— 用户提供文件或 URL

如果用户提供：
- 一个文件
- 一个文档路径
- 一个待摄取的 PDF/URL

则：

1. 执行摄取：
   ```bash
   python `skills/scripts/ingest.py` --file <path> --name "<document_name>"
   ```
   或
   ```bash
   python `skills/scripts/ingest.py` --url "<url>" --name "<document_name>"
   ```

2. 捕获返回的 `document_id`。

3. 轮询文档状态：
   ```bash
   python `skills/scripts/manage.py` status --id <document_id>
   ```
   重复直到 status == `ready`。

4. 继续进行检索（情形 C）。

---

## 情形 B —— 用户请求文档管理

### 列出文档
```bash
python `skills/scripts/manage.py` list
```

### 检查文档状态
```bash
python `skills/scripts/manage.py` status --id <document_id>
```

### 删除文档
```bash
python `skills/scripts/manage.py` delete --id <document_id>
```

向用户返回结构化结果。

---

## 情形 C —— 检索（有依据的问答）

执行：

```bash
python `skills/scripts/retrieve.py` \
  --query "<user_question>" \
  --top-k 6 \
  --rerank
```

可选标志：
- `--partition <name>`
- `--filter '{"key":"value"}'`

---

# 检索输出格式

预期输出：

```json
[
  {
    "text": "...",
    "score": 0.87,
    "document_name": "Policy Handbook",
    "document_id": "doc_abc123"
  }
]
```

---

# 有依据的提示词构造

检索之后：

1. 提取所有分块的 `text`。
2. 用分隔符连接。
3. 构造此提示词：

```
SYSTEM:
You are a helpful assistant.
Answer using ONLY the context provided below.
If the context does not contain the answer, say:
"I don't have that information in the current knowledge base."

CONTEXT:
[chunk 1 text]
---
[chunk 2 text]
---
...

USER QUESTION:
{original user question}
```

4. 生成最终答案。
5. 引用信息时标注 `document_name`。

---

# 输出契约

最终响应必须：

- 仅以检索到的分块为依据
- 对事实性陈述标注 `document_name`
- 避免臆造
- 避免提及内部执行步骤
- 避免暴露 API 密钥或原始响应
- 在信息缺失时明确说明

如果未返回任何分块：
```
I don't have that information in the current knowledge base.
```

---

# API 参考

基础 URL：
```
https://api.ragie.ai
```

| 操作               | 方法   | 端点                     |
|--------------------|--------|--------------------------|
| 摄取文件           | POST   | /documents               |
| 摄取 URL           | POST   | /documents/url           |
| 检索分块           | POST   | /retrievals              |
| 列出文档           | GET    | /documents               |
| 获取文档           | GET    | /documents/{id}          |
| 删除文档           | DELETE | /documents/{id}          |

---

# 错误处理

| HTTP 码 | 含义                   | 操作                            |
|-----------|------------------------|----------------------------------|
| 404       | 未找到文档             | 验证 document_id                |
| 422       | 无效负载               | 校验请求模式                    |
| 429       | 触发限流               | 带退避重试                      |
| 5xx       | 服务器错误             | 重试或检查 Ragie 状态           |

如果摄取失败：
- 清楚地报告失败。
- 不要继续进行检索。

如果检索失败：
- 重试一次。
- 若仍失败，告知用户。

---

# 决策规则摘要

1. 如果用户上传内容 → 摄取 → 等待至就绪 → 检索。
2. 如果用户提问 → 立即检索。
3. 如果零分块 → 说明知识缺口。
4. 始终使用重排序，除非明确禁用。
5. 永不在未检索的情况下回答。

---

# 高级用法

- 使用元数据 `filter` 缩小检索范围。
- 使用分区来隔离租户数据。
- 仅当时间相关性重要时才使用 `recency_bias`。
- 根据查询复杂度调整 `top_k`。

---

# 安全

- API 密钥必须从环境变量加载。
- 不得提交 `.env`。
- 不要记录敏感的请求头。

---

# 摘要

此技能提供：

- 确定性摄取
- 确定性检索
- 严格的有依据回答
- 完整的 Ragie 生命周期管理
- 安全且抗臆造的 RAG 执行

技能结束。