跳转到主要内容
文件类别（File Category）是 DocFlow 中用于组织和定义文档类型的核心概念。每个文件类别可以配置字段、表格、样本等，用于文档分类和智能抽取。

​
核心概念

在开始使用文件类别 API 之前，了解以下核心概念将帮助你更好地理解系统的工作原理：

​
样本文件

样本文件是该文件类别的典型示例文档。DocFlow 使用这些样本来：
  • 训练分类模型：帮助系统识别和区分不同类型的文档
  • 优化抽取效果：通过学习样本的格式和布局特征，提高字段抽取的准确度
  • 建立识别模板：为自动识别同类文档提供参考基准
要求：每个文件类别至少需要 1 个样本文件，最多 10 个，建议上传 3-5 个具有代表性的样本以获得最佳效果。

​
基本信息字段

基本信息字段是指在文档中以非表格形式存在的关键信息，每个字段包含字段名（key）和对应的值（value）。字段可能跨页或跨行显示。 抽取结果位置：字段信息在抽取结果中位于 result.files[].data.fields[]，每个字段包含：
  • key：字段名称（如”发票代码”、“开票日期”等）
  • value：字段值（识别出的文本内容）
  • position[]：字段在文档中的位置坐标信息
典型应用场景：
  • 发票类别：发票代码、发票号码、开票日期、购买方名称、金额合计
  • 合同类别：合同编号、甲方名称、乙方名称、签订日期、合同金额
  • 身份证类别：姓名、性别、民族、出生日期、身份证号码
配置字段的作用：
  • 明确告诉系统需要从文档中抽取哪些信息
  • 通过字段描述和提示词指导 AI 模型进行精准抽取
  • 定义字段的数据格式和验证规则

​
表格字段

表格字段是指以表格形式存在的结构化数据。DocFlow 能够识别文档中的表格结构，将表格内容转换为结构化的数据格式。表格由多行多列组成，每个表格可以配置多个字段（列）。 抽取结果位置：表格信息在抽取结果中位于 result.files[].data.items[][]，采用二维数组结构：
  • 外层数组：表示表格的行
  • 内层数组：表示行中的单元格
  • 每个单元格包含 key（列名）、value（单元格值）和 position（位置坐标）
典型应用场景：
  • 发票类别：货物明细表（货物劳务名称、规格型号、单位、数量、单价、金额）
  • 报销单类别：费用明细表（费用项目、日期、金额、备注）
  • 订单类别：订单明细表（商品名称、数量、单价、小计）
表格字段与基本字段的区别：
  • 基本字段：非表格形式的键值对，在 result.files[].data.fields[] 中返回，通常是文档的单个信息点
  • 表格字段：表格形式的结构化数据，在 result.files[].data.items[][] 中返回，支持一次抽取多行数据
  • 使用场景：基本字段适用于文档头部、尾部的固定信息；表格字段适用于明细、列表类的重复性结构化信息

​
快速开始

本文介绍如何使用文件类别相关接口：创建、查看、更新与删除文件类别。

​
创建文件类别

创建一个新的文件类别，需要上传至少一个样本文件并配置至少一个字段： 
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 "name=发票" \
  -F "category_prompt=增值税发票，包含发票代码、发票号码等字段" \
  -F "extract_model=llm" \
  -F "sample_files=@/path/to/invoice_sample.pdf" \
  -F 'fields=[{"name":"发票代码","description":"发票代码描述","prompt":"请抽取发票代码"}]' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/create"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • name (必填): 文件类别名称，最大长度 50
  • category_prompt (选填): 用于分类的提示词，最大长度 500
  • extract_model (必填): 抽取模型，可选值：llm、vlm
  • sample_files (必填): 样本文件列表，至少上传一个样本文件；每个类别最多拥有10个样本文件
  • fields (必填): 字段配置列表（JSON 字符串），至少配置一个字段，表格字段仅允许配置默认表格中的字段（table_id=-1）
响应示例： 
{
  "code": 200,
  "msg": "success",
  "result": {
    "category_id": "1234567890"
  }
}

​
获取文件类别列表

获取工作空间下的所有文件类别列表： 
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/list?workspace_id=<your-workspace-id>&page=1&page_size=20&enabled=1"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • page (选填): 页码，默认为 1
  • page_size (选填): 每页数量，默认为 1000
  • enabled (选填): 启用状态，可选值：all(所有)、1(启用)、0(禁用)、2(草稿)，默认为 1
响应示例： 
{
  "code": 200,
  "msg": "success",
  "result": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "categories": [
      {
        "id": "1234567890",
        "name": "发票",
        "category_prompt": "增值税发票，包含发票代码、发票号码等字段",
        "extract_model": "llm",
        "enabled": 1
      }
    ]
  }
}

​
更新文件类别

更新指定文件类别的信息： 
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": "1234567890",
    "name": "更新后的类别名称",
    "category_prompt": "更新后的提示词",
    "enabled": 1
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/update"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_id (必填): 文件类别 ID
  • name (选填): 文件类别名称，最大长度 50
  • category_prompt (选填): 用于分类的提示词，最大长度 500
  • enabled (选填): 启用状态，0: 禁用, 1: 启用, 2: 草稿

​
删除文件类别

删除指定的文件类别（可以批量删除）： 
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_ids": ["1234567890", "0987654321"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/delete"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_ids (必填): 要删除的文件类别 ID 数组
删除文件类别会同时删除其下的所有字段、表格和样本，请谨慎操作。

​
下一步