> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 样本管理

> 管理文件类别的样本文件

> [!TIP]
>
> 样本文件是文件类别的示例文档，用于训练和优化文档分类与抽取模型。每个文件类别至少需要一个样本文件，最多 20 个样本文件。本文介绍如何通过 API 管理文件类别的样本文件。

## 上传样本

为指定文件类别批量上传样本文件：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "workspace_id=<your-workspace-id>" \
  -F "category_id=<category-id>" \
  -F "files=@/path/to/sample1.pdf" \
  -F "files=@/path/to/sample2.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/sample/batch_upload"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/sample/batch_upload"

# 准备样本文件（支持多个）
files = [
    ("files", ("sample1.pdf", open('/path/to/sample1.pdf', 'rb'))),
    ("files", ("sample2.pdf", open('/path/to/sample2.pdf', 'rb'))),
]

# 准备表单数据
data = {
    'workspace_id': workspace_id,
    'category_id': category_id
}

resp = requests.post(
    url=f"{host}{url}",
    data=data,
    files=files,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=60,
)

result = resp.json()
if result.get("code") == 200:
    sample_ids = result.get("result", {}).get("sample_ids", [])
    print(f"样本上传成功，IDs: {sample_ids}")
else:
    print(f"上传失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `files` (必填): 样本文件，单次请求最多上传 20 个；上传后该类别的样本总数不能超过 20 个，因此实际可上传数量为 `20 - 当前已有样本数`

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "sample_ids": ["sample_123", "sample_456"]
  }
}
```

> [!NOTE]
>
> **样本文件要求**：
>
> * 样本文件应该是该类别的典型代表文档
> * 建议上传 3-5 个样本文件以提高分类准确度
> * 每个类别最多保留 20 个样本；追加上传时请扣除该类别已有样本数
> * 支持的文件格式参考文档上传支持的格式

## 获取样本列表

获取指定文件类别的样本列表：

```bash curl icon=terminal wrap theme={null}
curl \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/sample/list?workspace_id=<your-workspace-id>&category_id=<category-id>&page=1&page_size=20"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/sample/list"

resp = requests.get(
    url=f"{host}{url}",
    params={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "page": 1,
        "page_size": 20
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    samples = result.get("result", {}).get("samples", [])
    total = result.get("result", {}).get("total", 0)
    print(f"共找到 {total} 个样本")
    for sample in samples:
        print(f"样本ID: {sample.get('sample_id')}, 文件名: {sample.get('file_name')}")
else:
    print(f"获取失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `page` (选填): 页码，默认为 1
* `page_size` (选填): 每页数量，默认为 20，最大为100

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "total": 5,
    "page": 1,
    "page_size": 20,
    "samples": [
      {
        "sample_id": "sample_123",
        "file_name": "invoice_sample_01.pdf"
      },
      {
        "sample_id": "sample_456",
        "file_name": "invoice_sample_02.pdf"
      }
    ]
  }
}
```

## 下载样本

批量下载指定的样本文件：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -o "samples.zip" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "sample_ids": ["<sample-id>"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/sample/batch_download"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
sample_id = "<sample-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/sample/batch_download"

resp = requests.post(
    url=f"{host}{url}",
    json={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "sample_ids": [sample_id]
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=60,
)

if resp.status_code == 200:
    # 保存文件
    with open("samples_downloaded.zip", "wb") as f:
        f.write(resp.content)
    print("样本下载成功")
else:
    print(f"下载失败: {resp.status_code}")
```

**请求参数（JSON Body）：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `sample_ids` (必填): 样本 ID 数组

**响应**：返回文件二进制流（`application/octet-stream`）

## 删除样本

删除指定的样本文件，支持批量删除：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "sample_ids": ["sample_123", "sample_456"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/sample/delete"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/sample/delete"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "sample_ids": ["sample_123", "sample_456"]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    print("样本删除成功")
else:
    print(f"删除失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `sample_ids` (必填): 要删除的样本 ID 数组

> [!WARNING]
>
> 删除样本后无法恢复，请谨慎操作。每个文件类别至少需要保留一个样本文件。

## 样本管理最佳实践

### 样本选择

选择合适的样本文件对提高分类和抽取准确度至关重要：

1. **典型性**：选择该类别的典型代表文档
2. **多样性**：覆盖该类别可能出现的不同格式和版式
3. **质量**：确保样本文件清晰、完整、无损坏
4. **数量**：建议上传 3-5 个样本文件

### 样本数量建议

* **最少数量**：每个类别至少 1 个样本（创建类别时必需）
* **推荐数量**：3-5 个样本可以提供较好的分类效果
* **最多数量**：每个类别最多 20 个样本

### 样本更新策略

当发现分类或抽取效果不理想时，可以考虑：

1. **添加新样本**：上传更多典型样本
2. **替换样本**：删除不典型的样本，上传更好的样本
3. **样本多样化**：确保样本覆盖各种可能的文档格式

### 示例：批量上传样本

```python Python icon=python expandable theme={null}
import requests
import os

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/sample/batch_upload"

# 样本文件目录
sample_dir = "/path/to/samples"
sample_files = [f for f in os.listdir(sample_dir) if f.endswith('.pdf')]

print(f"准备上传 {len(sample_files)} 个样本文件")

# 构建多文件上传列表
files = [
    ("files", (filename, open(os.path.join(sample_dir, filename), 'rb')))
    for filename in sample_files
]

data = {
    'workspace_id': workspace_id,
    'category_id': category_id
}

resp = requests.post(
    url=f"{host}{url}",
    data=data,
    files=files,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=60,
)

result = resp.json()
if result.get("code") == 200:
    sample_ids = result.get("result", {}).get("sample_ids", [])
    print(f"批量上传成功，共 {len(sample_ids)} 个样本")
    for sid in sample_ids:
        print(f"  样本ID: {sid}")
else:
    print(f"上传失败: {result.get('msg')}")

# 关闭文件句柄
for _, (_, f) in files:
    f.close()

print("样本上传完成")
```

## 下一步

* 学习[字段管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/fields_management.md) - 配置文件类别的字段
* 学习[表格管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/tables_management.md) - 配置文件类别的表格
* 返回[文件类别快速启动](https://docs-docflow.textin.com/docflow/cn/10-category-management/quickstart.md) - 查看文件类别基础操作


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.