样本中心对外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 任务处理逻辑

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

9.5 任务类型扩展

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

task_type	说明
bi	批量入库任务

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

样本中心提供API接口文档_外部.md 15 KB Előzmények Nyers

样本中心对外API接口文档

1. 概述

1.1 文档目的

1.2 基础信息

2. 认证与鉴权

2.1 Token 设计方案

2.1.1 凭证分配

2.1.2 获取访问令牌

2.1.3 Token 使用

2.1.4 Token 管理规则

3. 统一响应格式

3.1 错误码定义

4. 接口详情

4.1 知识库列表查询

4.2 知识库详情查询

4.3 知识库批量入库

4.4 批量入库任务查询

5. 任务状态流转

6. 轮询与回调机制

6.1 轮询方式

6.2 回调方式（可选）

7. 接口总览

9. 异步任务表设计

9.1 表结构定义

9.2 任务状态枚举

9.3 回调状态枚举

9.4 任务处理逻辑

9.5 任务类型扩展

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

Előzmények Nyers