Home Explore Help
Register Sign In
Maas2-group
/
Fine-tuning
5
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 9ae2189158
Branches Tags
Fine-tuning
/
样本中心提供API接口文档_外部.md

样本中心提供API接口文档_外部.md 15 KB
History Raw

样本中心对外API接口文档

1. 概述

1.1 文档目的

本文档定义样本中心对外提供的API接口规范，供外部系统（如采集系统）接入使用。

1.2 基础信息

项目 说明
Base URL https://{host}/api/v1
数据格式 JSON
字符编码 UTF-8
认证方式 Bearer Token

2. 认证与鉴权

2.1 Token 设计方案

采用 API Key + Secret 签名机制，外部系统通过以下方式获取访问 Token：

2.1.1 凭证分配

每个接入系统在样本中心注册后，分配一对凭证：

  • app_id：应用唯一标识
  • app_secret：应用密钥（仅初始化时展示一次，需妥善保存）

2.1.2 获取访问令牌

POST /api/v1/auth/token

项目 说明
Content-Type application/json

请求参数：

参数名 类型 必录 说明
app_id string 是 应用标识
app_secret string 是 应用密钥

请求示例：

{
  "app_id": "collect_system_001",
  "app_secret": "sk_xxxxxxxxxxxxxxxx"
}

响应参数：

参数名 类型 说明
access_token string 访问令牌
expires_in integer 过期时间（秒），默认 7200
token_type string 令牌类型，固定 "Bearer"

响应示例：

{
  "code": "000000",
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

2.1.3 Token 使用

所有业务接口需在 HTTP Header 中携带 Token：

Authorization: Bearer {access_token}
X-App-Id: {app_id}

2.1.4 Token 管理规则

  • Token 有效期 2 小时，过期后需重新获取
  • 支持多 Token 并存，新 Token 获取不影响旧 Token 使用
  • 单 app_id 同时最多持有 3 个有效 Token
  • Token 被吊销后即时失效

3. 统一响应格式

所有接口返回统一的 JSON 结构：

{
  "code": "000000",
  "message": "success",
  "data": { ... },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}
参数名 类型 说明
code string 状态码，"000000" 表示成功，非 "000000" 表示失败
message string 提示信息
data object/array/null 业务数据
request_id string 请求追踪 ID

3.1 错误码定义

错误码 说明
000000 成功
000400 请求参数错误
000401 认证失败（Token 无效/过期）
000403 权限不足
000404 资源不存在
000429 请求频率超限
000500 服务端内部错误
001001 知识库不存在
001002 知识库未启用
002001 批量入库参数校验失败
002002 批量入库任务不存在
002003 批量入库任务数据格式错误

4. 接口详情

4.1 知识库列表查询

GET /api/v1/knowledge-bases

查询当前应用有权限访问的已启用知识库列表。

请求参数（Query）：

参数名 类型 必录 说明
page integer 否 页码，默认 1
page_size integer 否 每页条数，默认 20，最大 100

响应参数：

{
  "code": "000000",
  "message": "success",
  "data": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "id": "5138215886300893584",
        "name": "建设工程知识库",
        "parent_table": "kb_parent_table_001",
        "child_table": "kb_child_table_001",
        "document_count": 1520,
        "status": 1,
        "created_at": "2026-05-10T10:30:00Z",
        "created_by": "admin",
        "metadata_schema": [
          {
            "field_name_cn": "文档编号",
            "field_name_en": "doc_number",
            "field_type": "string",
            "description": "文档的唯一编号"
          },
          {
            "field_name_cn": "发布日期",
            "field_name_en": "publish_date",
            "field_type": "date",
            "description": "文档发布日期"
          }
        ]
      }
    ]
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}

列表项字段说明：

参数名 类型 说明
id string 知识库ID
name string 知识库名称
parent_table string 父集合表名
child_table string 子集合表名
document_count integer 文档数量
status integer 状态：1-启用，0-禁用
created_at string 创建时间，ISO 8601 格式
created_by string 创建人
metadata_schema array 元数据字典定义列表

metadata_schema 字段说明：

参数名 类型 说明
field_name_cn string 字段中文名称
field_name_en string 字段英文名称
field_type string 字段类型：string/integer/float/date/boolean/array
description string 字段描述

4.2 知识库详情查询

GET /api/v1/knowledge-bases/{id}

查询指定知识库的详细信息，包括元数据字典定义。

路径参数：

参数名 类型 必录 说明
id string 是 知识库ID

响应参数：

{
  "code": "000000",
  "message": "success",
  "data": {
    "id": "5138215886300893584",
    "name": "建设工程知识库",
    "description": "建设工程相关法规文档",
    "parent_table": "kb_parent_table_001",
    "child_table": "kb_child_table_001",
    "document_count": 1520,
    "status": 1,
    "created_at": "2026-05-10T10:30:00Z",
    "created_by": "admin",
    "updated_at": "2026-05-15T14:20:00Z",
    "metadata_schema": [
      {
        "field_name_cn": "文档编号",
        "field_name_en": "doc_number",
        "field_type": "string",
        "description": "文档的唯一编号"
      },
      {
        "field_name_cn": "发布日期",
        "field_name_en": "publish_date",
        "field_type": "date",
        "description": "文档发布日期"
      },
      {
        "field_name_cn": "文档来源",
        "field_name_en": "source",
        "field_type": "string",
        "description": "文档来源机构"
      }
    ]
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}

4.3 知识库批量入库

POST /api/v1/knowledge-bases/{kb_id}/batch-import

提交批量入库任务，系统将片段向量化后存入向量数据库。

路径参数：

参数名 类型 必录 说明
kb_id string 是 知识库ID

请求体：

{
  "task_no": "IMP202605170001",
  "callback_url": "https://collect-system.example.com/api/callback/import-result",
  "parents": [
    {
      "index": 0,
      "parent_id": "5138215886300893584",
      "hierarchy": "建设工程质量管理条例",
      "text": "第一条 为了加强对建设工程质量的管理...",
      "metadata": {
        "doc_number": "国务院令第279号",
        "publish_date": "2000-01-30"
      },
      "doc_id": "doc_001",
      "tag_list": ["法规", "质量管理"],
      "permission": {
        "visible_roles": ["role_admin", "role_engineer"],
        "visible_users": ["user_001"]
      }
    }
  ],
  "children": [
    {
      "index": 0,
      "parent_id": "5138215886300893584",
      "hierarchy": "第一章 总则",
      "text": "第一条 为了加强对建设工程质量的管理，保证建设工程质量...",
      "metadata": {
        "doc_number": "国务院令第279号",
        "section": "第一章"
      },
      "doc_id": "doc_001",
      "tag_list": ["法规", "总则"],
      "permission": {
        "visible_roles": ["role_admin"]
      }
    }
  ]
}

请求参数说明：

参数名 类型 必录 说明
task_no string 是 入库任务号，由调用方生成，用于记录当前入库任务状态及后续查询进度
callback_url string 否 回调地址，任务完成后样本中心将处理结果推送至该地址，不传则不回调
parents array 是 父段信息列表
children array 否 子段信息列表

parents/children 项字段说明：

参数名 类型 必录 说明
index integer 是 分片索引号
parent_id string 是 父段ID，子段通过此字段关联父段
hierarchy string 否 章节信息
text string 是 段文本信息
metadata object 否 段元数据信息，键值对结构
doc_id string 否 文档ID
tag_list array 否 标签列表
permission object 否 权限配置

permission 字段说明：

参数名 类型 说明
visible_roles array 可见角色 ID 列表
visible_users array 可见用户 ID 列表

响应参数：

{
  "code": "000000",
  "message": "success",
  "data": {
    "task_id": "task_20260517xxxxxxxx",
    "status": "pending"
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}
参数名 类型 说明
task_id string 任务ID
status string 任务状态：pending-待处理

4.4 批量入库任务查询

GET /api/v1/knowledge-bases/batch-import/{task_id}

查询批量入库任务的处理状态和结果。

路径参数：

参数名 类型 必录 说明
task_id string 是 入库任务ID

响应参数：

进行中：

{
  "code": "000000",
  "message": "success",
  "data": {
    "task_id": "task_20260517xxxxxxxx",
    "task_no": "IMP202605170001",
    "status": "processing",
    "progress": {
      "total": 100,
      "processed": 45,
      "succeeded": 43,
      "failed": 2
    },
    "created_at": "2026-05-17T10:00:00Z",
    "updated_at": "2026-05-17T10:01:30Z"
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}

已完成：

{
  "code": "000000",
  "message": "success",
  "data": {
    "task_id": "task_20260517xxxxxxxx",
    "task_no": "IMP202605170001",
    "status": "completed",
    "progress": {
      "total": 100,
      "processed": 100,
      "succeeded": 98,
      "failed": 2
    },
    "created_at": "2026-05-17T10:00:00Z",
    "completed_at": "2026-05-17T10:05:00Z",
    "failures": [
      {
        "index": 12,
        "parent_id": "5138215886300893584",
        "error": "文本内容为空，跳过入库"
      },
      {
        "index": 56,
        "parent_id": "5138215886300893584",
        "error": "向量化模型调用超时"
      }
    ]
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}

失败：

{
  "code": "000000",
  "message": "success",
  "data": {
    "task_id": "task_20260517xxxxxxxx",
    "task_no": "IMP202605170001",
    "status": "failed",
    "error": "向量数据库连接异常",
    "created_at": "2026-05-17T10:00:00Z",
    "completed_at": "2026-05-17T10:00:05Z"
  },
  "request_id": "req_xxxxxxxxxxxxxxxx"
}

字段说明：

参数名 类型 说明
task_id string 任务ID，系统生成
task_no string 入库任务号，调用方传入
status string 任务状态：pending-待处理，processing-处理中，completed-已完成，failed-失败
progress object 进度信息
progress.total integer 总条数
progress.processed integer 已处理条数
progress.succeeded integer 成功条数
progress.failed integer 失败条数
failures array 失败明细列表
error string 整体失败原因（仅 status=failed 时返回）
created_at string 任务创建时间
updated_at string 状态更新时间
completed_at string 任务完成时间

5. 任务状态流转

pending → processing → completed
                      → failed
状态 说明
pending 任务已接收，排队等待处理
processing 任务正在处理中
completed 任务处理完成（可能部分失败）
failed 任务整体失败，无数据入库

6. 轮询与回调机制

6.1 轮询方式

外部系统提交任务后，通过 GET /api/v1/knowledge-bases/batch-import/{task_id} 轮询任务状态。

建议轮询策略：

  • 初始间隔 2 秒
  • 每次轮询后间隔 × 1.5，上限 30 秒
  • 任务终态（completed/failed）后停止轮询

6.2 回调方式（可选）

外部系统在提交批量入库任务时，若无法主动轮询，可在请求体中传入 callback_url。任务完成后样本中心主动向该地址推送处理结果。

回调请求： POST {callback_url}

{
  "task_id": "task_20260517xxxxxxxx",
  "task_no": "IMP202605170001",
  "status": "completed",
  "kb_id": "5138215886300893584",
  "progress": {
    "total": 100,
    "processed": 100,
    "succeeded": 98,
    "failed": 2
  },
  "completed_at": "2026-05-17T10:05:00Z"
}

回调失败时最多重试 3 次，间隔 10s / 30s / 60s。

7. 接口总览

序号 方法 路径 说明
1 POST /api/v1/auth/token 获取访问令牌
2 GET /api/v1/knowledge-bases 知识库列表查询
3 GET /api/v1/knowledge-bases/{id} 知识库详情查询
4 POST /api/v1/knowledge-bases/{kb_id}/batch-import 批量入库提交
5 GET /api/v1/knowledge-bases/batch-import/{task_id} 入库任务查询

9. 异步任务表设计

9.1 表结构定义

表名：t_samp_task_management

样本中心异步任务表，用于记录所有异步任务的生命周期。

9.2 任务状态枚举

状态值 说明
pending 任务已接收，排队等待处理
processing 任务正在处理中
completed 任务处理完成（可能部分失败）
failed 任务整体失败，无数据入库

9.3 回调状态枚举

状态值 说明
pending 待处理
processing 处理中
success 回调成功
failed 回调失败

9.4 任务处理逻辑

  1. 任务接收：批量入库任务接收请求后，先将任务保存到任务表，状态设为 pending
  2. 异步处理：发起异步任务进行知识片段入库处理，同时更新任务表状态为 processing
  3. 任务完成：处理完成后更新任务表状态为 completed，记录完成时间
  4. 任务失败：处理失败时更新任务表状态为 failed，同时写入错误信息到 error_message
  5. 回调通知：任务处理完成后，若 callback_url 不为空，则发起回调请求，并根据回调结果更新 callback_status
  6. 状态查询：入库任务查询接口直接查询任务表的 status 和 callback_status

9.5 任务类型扩展

任务表通过 task_type 字段支持多种任务类型，当前支持：

task_type 说明
bi 批量入库任务

后续可按需扩展其他任务类型（如：批量删除、数据同步等）。