From 1eda7d608e42045faa5496eff7f944505956ac87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BA=90=E5=B1=B1=E7=83=9F=E9=9B=A8?= <114392400+Fangjj0621@users.noreply.github.com> Date: Mon, 1 Dec 2025 16:49:41 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=8E=9F=E5=AD=90API?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 每个节点的参数还需要再补充 --- .../structured_extraction_api.md | 121 -- .../workflow api/automic_api.md | 756 ++++++++++++ .../workflow api/data_explore_api.md | 1053 ----------------- mkdocs.yml | 3 +- 4 files changed, 757 insertions(+), 1176 deletions(-) delete mode 100644 docs/MatrixOne-Intelligence/quick-start api/structured_extraction_api.md create mode 100644 docs/MatrixOne-Intelligence/workflow api/automic_api.md delete mode 100644 docs/MatrixOne-Intelligence/workflow api/data_explore_api.md diff --git a/docs/MatrixOne-Intelligence/quick-start api/structured_extraction_api.md b/docs/MatrixOne-Intelligence/quick-start api/structured_extraction_api.md deleted file mode 100644 index f6c0d787..00000000 --- a/docs/MatrixOne-Intelligence/quick-start api/structured_extraction_api.md +++ /dev/null @@ -1,121 +0,0 @@ -# 结构化抽取 API - -## 概述 - -结构化抽取 API 能够从 PDF 文件中提取关键信息并转换为结构化数据，支持自定义 JSON Schema 模板。 - -**主要使用场景：** - -- PDF 简历信息抽取 -- 合同文档关键信息提取 -- 发票 PDF 数据结构化 -- 报告文档信息整理 -- 证书文档数据化 - -## API 端点 - -``` -POST https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/extract -``` - -## 请求头 - -| 参数名 | 类型 | 是否必填 | 描述 | -|--------|------|----------|------| -| moi-key | String | 是 | API 密钥 | -| Content-Type | String | 是 | 固定值：application/json | - -## 请求参数 - -| 参数名 | 类型 | 是否必填 | 描述 | -|--------|------|----------|------| -| file_path | String | 是 | PDF 文件的 URL 地址 | -| json_schema | Object | 是 | JSON Schema 抽取模式定义 | - -## 请求示例 - -### Python 示例 - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/extract" -headers = { - "moi-key": "your-api-key", - "Content-Type": "application/json" -} - -data = { - "file_path": "http://120.26.117.79:8080/files/xiyou.pdf", - "json_schema": { - "title": "ExtractInfo", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "联系邮箱" - }, - "book_name": { - "type": "string", - "description": "书名" - } - }, - "required": [ - "email", - "book_name" - ] - } -} - -response = requests.post(url, headers=headers, json=data) -print(response.json()) -``` - -### cURL 示例 - -```bash -curl --location --request POST 'https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/extract' \ ---header 'moi-key: your-api-key' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "file_path": "http://120.26.117.79:8080/files/xiyou.pdf", - "json_schema": { - "title": "ExtractInfo", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "联系邮箱" - }, - "book_name": { - "type": "string", - "description": "书名" - } - }, - "required": [ - "email", - "book_name" - ] - } -}' -``` - -## 响应格式 - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "req_id": "607654fa-f12b-4415-a4c4-38dd07c7926e", - "msg": "success", - "file_path": "http://120.26.117.79:8080/files/xiyou.pdf", - "file_size_bytes": 1562886, - "results": { - "email": "466698432@qq.com", - "book_name": "西游记" - } - } -} -``` \ No newline at end of file diff --git a/docs/MatrixOne-Intelligence/workflow api/automic_api.md b/docs/MatrixOne-Intelligence/workflow api/automic_api.md new file mode 100644 index 00000000..4751a8a0 --- /dev/null +++ b/docs/MatrixOne-Intelligence/workflow api/automic_api.md @@ -0,0 +1,756 @@ +# MOI 原子能力 API 文档 + +## 概述 + +MOI 原子能力 API 是一个用于处理文件的异步管道服务，支持对文件进行解析、分析等多种处理操作。该 API 采用异步处理模式，提交任务后会返回 job_id 用于后续查询处理结果。 + +### API 列表 + +本文档包含以下 API： + +| API 名称 | 请求方法 | 端点 | 功能说明 | +|---------|---------|------|---------| +| 提交文件处理任务 | POST | `/v1/genai/pipeline` | 提交文件进行处理，支持远程 URL、本地上传或混合使用 | +| 查询任务状态 | GET | `/v1/genai/jobs/{job_id}` | 查询已提交任务的处理状态和文件列表 | +| 获取处理结果 | GET | `/byoa/api/v1/explore/volumes/any/files/{file_id}/raws` | 下载文件处理后的结果数据（ZIP 压缩包） | + +--- + +## 提交文件处理任务 + +### 基本信息 + +- **API 地址**: `https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline` +- **请求方法**: `POST` +- **请求格式**: + - `application/json` 用于远程文件 URL + - `multipart/form-data` 用于本地文件上传 +- **响应格式**: `application/json` + +### 调用方式 + +该 API 支持灵活的文件处理方式： + +**方式一：公网文件 URL** + +- 使用 `application/json` 格式 +- 通过 `file_urls` 参数传递公网文件地址 +- 适用于处理已在网络上的文件 + +**方式二：本地文件上传** + +- 使用 `multipart/form-data` 格式 +- 通过文件上传方式传递本地文件 +- 需要同时传递 `payload` 和 `files` 字段 +- 适用于上传本地文件进行处理 + +**方式三：混合处理** + +- **支持同时处理公网文件和本地文件** +- 使用 `multipart/form-data` 格式 +- 在 `payload` 中同时指定 `file_urls`（公网文件）和 `file_names`（本地文件） +- 上传本地文件的同时指定公网文件 URL +- API 会一次性处理所有文件（公网 + 本地），返回单一 job_id + +### 请求头 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| Content-Type | String | 视情况 | 远程 URL 方式：`application/json`
本地上传方式：`multipart/form-data` | +| moi-key | String | 是 | API 密钥，用于身份验证 | + +**示例：** + +远程文件 URL 方式： + +``` +Content-Type: application/json +moi-key: YOUR-MOI-KEY +``` + +本地文件上传方式： + +``` +moi-key: YOUR-MOI-KEY +``` + +注：使用 `-F` 参数时，curl 会自动设置 `Content-Type: multipart/form-data` + +### 请求参数 + +**方式一：远程文件 URL** + +直接发送 JSON 格式的请求体： + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| file_urls | Array[String] | 是 | 待处理文件的 URL 列表，支持 HTTP/HTTPS 协议的文件地址 | +| file_names | Array[String] | 否 | 保持为空数组 `[]` | +| meta | Array | 否 | 元数据信息，可用于传递额外的处理参数或标识信息 | +| steps | Array[Object] | 是 | 处理步骤配置，定义对文件执行的操作流程 | +| steps[].node | String | 是 | 处理节点名称，如：`ParseNode` | +| steps[].parameters | Object | 是 | 节点处理参数，根据不同节点类型传入不同配置，可为空对象 | + +**方式二：本地文件上传** + +使用 `multipart/form-data` 格式，包含以下字段： + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| payload | String | 是 | JSON 字符串，包含配置信息 | +| payload.file_names | Array[String] | 是 | 上传的文件名列表，需与实际上传的文件对应 | +| payload.meta | Array | 否 | 元数据信息 | +| payload.steps | Array[Object] | 是 | 处理步骤配置 | +| files | File | 是 | 实际上传的文件，支持多文件上传 | + +**参数说明：** + +- 两种方式选择其一即可 +- `steps` 数组定义了文件处理的流程，**按顺序执行** +- 本地上传时，`file_names` 中的文件名应与实际上传的文件名匹配 +- 节点之间有依赖关系，必须按照正确的顺序配置 + +### 处理节点类型 + +**支持的处理节点：** + +| 节点名称 | 功能说明 | 输入 | 输出 | +|---------|---------|------|------| +| ParseNode | 解析节点 | 原始文件 | 结构化数据（文本、表格、图片） | +| ChunkNode | 分块节点 | ParseNode 输出 | 文本块（chunks） | +| EmbedNode | 嵌入节点 | ChunkNode 输出 | 向量嵌入（embeddings） | +| ExtractNode | 提取节点 | 原始文件或其他节点输出 | 特定信息提取 | + +**节点组合方式：** + +处理节点可以按以下方式组合（必须按顺序）： + +**1. 仅解析** + +```json +"steps": [ + {"node": "ParseNode", "parameters": {}} +] +``` + +用途：仅解析文件，提取文本、表格、图片 + +**2. 解析 + 分块** + +```json +"steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}} +] +``` + +用途：解析文件后将内容分成小块，便于后续处理 + +**3. 解析 + 分块 + 嵌入** + +```json +"steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}}, + {"node": "EmbedNode", "parameters": {}} +] +``` + +用途：完整的文档向量化流程，适用于语义搜索 + +**4. 解析 + 分块 + 嵌入 + 提取** + +```json +"steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}}, + {"node": "EmbedNode", "parameters": {}}, + {"node": "ExtractNode", "parameters": {}} +] +``` + +用途：解析后提取，包含解析、分块、向量化和信息提取 + +**5. 仅提取** + +```json +"steps": [ + {"node": "ExtractNode", "parameters": {}} +] +``` + +用途：直接从文件中提取特定信息，不需要解析步骤 + +**节点参数说明：** + +每个节点可以配置 `parameters` 参数来自定义处理行为： + +```json +{ + "node": "NodeName", + "parameters": { + // 节点特定参数（可选） + // 如果使用默认配置，可传空对象 {} + } +} +``` + +**注意**: + +- 如无特殊需求，`parameters` 可以传空对象 `{}` +- 具体参数配置请咨询 API 提供方 +- 不同节点支持的参数可能不同 + +### 请求示例 + +**示例 1：使用远程文件 URL** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR-MOI-KEY" \ + -d '{ + "file_urls": [ + "http://www.pdf995.com/samples/pdf.pdf", + "https://example.com/document.pdf" + ], + "file_names": [], + "meta": [], + "steps": [ + { + "node": "ParseNode", + "parameters": {} + } + ] +}' +``` + +**说明：** + +- 使用 `-H "Content-Type: application/json"` 指定 JSON 格式 +- 使用 `-d` 参数传递 JSON 数据 +- `file_urls` 数组可以包含多个 URL +- `file_names` 设置为空数组 +- API 会依次处理所有文件，返回单一的 job_id + +**成功响应示例：** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "job_id": "b55093a7-ff3c-42ca-a4fe-c4e72074e046" + }, + "request_id": "969935d0-363e-4451-a5e3-f71f1d20101e" +} +``` + +**示例 2：上传本地文件** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "moi-key: YOUR-MOI-KEY" \ + -F "files=@/path/to/doc1.pdf" \ + -F "files=@/path/to/doc2.pdf" \ + -F 'payload={"file_names": ["doc1.pdf", "doc2.pdf"], "steps": [{"node": "ParseNode", "parameters": {}}]}' +``` + +**说明：** + +- 使用 `-F` 参数指定 multipart/form-data 格式（不需要 Content-Type 头） +- 多次使用 `-F "files=@文件路径"` 上传多个文件 +- `files=@` 后跟文件路径，`@` 符号表示从文件读取内容 +- 所有文件字段都使用相同的字段名 `files` +- `payload` 为 JSON 字符串，包含配置信息 +- `file_names` 数组中的顺序应与上传的文件对应 +- 注意：`files` 字段在前，`payload` 字段在后 + +**成功响应示例：** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "job_id": "cd072050-ce02-406b-8f28-595f2c86eaaa" + }, + "request_id": "b6528fde-ebc3-461b-8015-1b7b97ec9c82" +} +``` + +**示例 3：混合使用** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "moi-key: YOUR-MOI-KEY" \ + -F "files=@2112205248_方佳俊_检测简明报告.pdf" \ + -F 'payload={"file_urls": ["http://www.pdf995.com/samples/pdf.pdf"], "file_names": ["2112205248_方佳俊_检测简明报告.pdf"], "steps": [{"node": "ParseNode", "parameters": {}}]}' +``` + +**说明：** + +- ✅ **支持同时使用本地文件和远程 URL** +- `file_urls` 包含远程文件 URL +- `file_names` 包含上传的本地文件名 +- `files` 字段上传本地文件内容 +- API 会处理所有文件（本地 + 远程），返回单一 job_id + +**成功响应示例：** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "job_id": "322fe48f-698d-4fbb-8851-1a2d9f8031ec" + }, + "request_id": "ec636405-82ce-4331-902b-6810a83d17f0" +} +``` + +**示例 4：解析 + 分块** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -d '{ + "file_urls": ["http://example.com/document.pdf"], + "file_names": [], + "steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}} + ] + }' +``` + +**说明：** + +- 先解析文件 +- 再将解析后的内容分块 +- 适用于需要对文档进行分段处理的场景 + +**示例 5：完整向量化流程** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -d '{ + "file_urls": ["http://example.com/document.pdf"], + "file_names": [], + "steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}}, + {"node": "EmbedNode", "parameters": {}} + ] + }' +``` + +**说明：** + +- 解析 → 分块 → 向量嵌入 +- 适用于构建语义搜索索引、RAG 系统等 +- 生成的向量可用于相似度搜索 + +**示例 6：完整流程** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -d '{ + "file_urls": ["http://example.com/document.pdf"], + "file_names": [], + "steps": [ + {"node": "ParseNode", "parameters": {}}, + {"node": "ChunkNode", "parameters": {}}, + {"node": "EmbedNode", "parameters": {}}, + {"node": "ExtractNode", "parameters": {}} + ] + }' +``` + +**说明：** + +- 解析 → 分块 → 向量嵌入 → 信息提取 +- 完整的文档处理流程 +- 适用于需要全面分析文档的场景 + +**示例 7：仅信息提取** + +```bash +curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -d '{ + "file_urls": ["http://example.com/document.pdf"], + "file_names": [], + "steps": [ + {"node": "ExtractNode", "parameters": {}} + ] + }' +``` + +**说明：** + +- 直接提取文件中的特定信息 +- 无需经过解析步骤 +- 适用于快速提取结构化数据 + +### 响应参数 + +**成功响应：** + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | String | 状态码，成功时为 `OK` | +| msg | String | 响应消息，成功时为 `OK` | +| data | Object | 响应数据对象 | +| data.job_id | String | 任务 ID，用于查询任务处理状态和结果 | +| request_id | String | 请求唯一标识，可用于问题追踪 | + +**成功响应示例：** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "job_id": "c66f4354-6833-4c75-8d34-d630024e5254" + }, + "request_id": "d16e0fc2-50dd-4928-9eac-d55f88e0160c" +} +``` + +**错误响应：** + +```json +{ + "code": "ERROR_CODE", + "msg": "错误描述信息", + "data": null, + "request_id": "请求 ID" +} +``` + +--- + +## 查询任务状态 + +### 基本信息 + +- **API 地址**: `https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/jobs/{job_id}` +- **请求方法**: `GET` +- **请求格式**: URL 路径参数 +- **响应格式**: `application/json` + +### 请求头 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| moi-key | String | 是 | API 密钥，用于身份验证 | + +### 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| job_id | String | 是 | 提交任务时返回的任务 ID | + +### 响应参数 + +**成功响应：** + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | String | 状态码，成功时为 `OK` | +| msg | String | 响应消息，成功时为 `OK` | +| data | Object | 响应数据对象 | +| data.status | String | 任务整体状态：`pending`、`processing`、`completed`、`failed` | +| data.files | Array[Object] | 文件列表，包含每个文件的处理详情 | +| data.files[].file_id | String | 文件唯一标识 ID | +| data.files[].file_name | String | 文件名称 | +| data.files[].file_type | Integer | 文件类型编号 | +| data.files[].file_status | String | 文件处理状态：`pending`、`processing`、`completed`、`failed` | +| data.files[].error_message | String | 错误信息，成功时为空字符串 | +| data.files[].start_time | String | 文件处理开始时间 | +| data.files[].end_time | String | 文件处理结束时间 | +| request_id | String | 请求唯一标识 | + +### 请求示例 + +**示例：查询任务状态** + +```bash +curl -X GET "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/jobs/322fe48f-698d-4fbb-8851-1a2d9f8031ec" \ + -H "moi-key: YOUR-MOI-KEY" +``` + +**说明：** + +- 使用 GET 方法 +- job_id 作为 URL 路径的一部分 +- 只需要 `moi-key` 认证头 + +### 响应示例 + +**示例 1：任务已完成** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "status": "completed", + "files": [ + { + "file_id": "019ad8c4-cf7e-75ca-afa1-5bd971ff9ed9", + "file_name": "2112205248_方佳俊_检测简明报告.pdf", + "file_type": 2, + "file_status": "completed", + "error_message": "", + "start_time": "2025-12-01T07:16:11.000000+0000", + "end_time": "2025-12-01T07:16:38.000000+0000" + } + ] + }, + "request_id": "2934576f-246e-46cf-93d1-79a95fd52251" +} +``` + +**示例 2：多文件任务已完成** + +```json +{ + "code": "OK", + "msg": "OK", + "data": { + "status": "completed", + "files": [ + { + "file_id": "019ad8cb-3861-795c-99a6-03bdc37215ee", + "file_name": "2112205248_方佳俊_检测简明报告.pdf", + "file_type": 2, + "file_status": "completed", + "error_message": "", + "start_time": "2025-12-01T07:23:38.000000+0000", + "end_time": "2025-12-01T07:24:40.000000+0000" + }, + { + "file_id": "019ad8cb-3861-7963-8fa5-e2e6b66a265c", + "file_name": "pdf.pdf", + "file_type": 2, + "file_status": "completed", + "error_message": "", + "start_time": "2025-12-01T07:23:39.000000+0000", + "end_time": "2025-12-01T07:25:38.000000+0000" + } + ] + }, + "request_id": "74983c96-98db-4e13-9d51-aee91dfcd163" +} +``` + +**说明：** + +- 混合上传的任务包含两个文件：本地上传的文件和远程 URL 文件 +- 每个文件都有独立的 `file_id`、处理状态和时间信息 +- 本例中两个文件都已成功完成处理 + +### 任务状态说明 + +**整体任务状态：** + +| 状态 | 说明 | +|------|------| +| pending | 任务已提交，等待处理 | +| processing | 任务正在处理中 | +| completed | 所有文件处理完成 | +| failed | 任务处理失败 | + +**单个文件状态：** + +| 状态 | 说明 | +|------|------| +| pending | 文件等待处理 | +| processing | 文件处理中 | +| completed | 文件处理成功 | +| failed | 文件处理失败，查看 `error_message` 了解原因 | + +### 注意事项 + +1. **轮询间隔**：建议每 3-5 秒查询一次任务状态，避免频繁请求 +2. **处理时间**： + - 小文件（<1MB）通常需要几秒到几十秒 + - 大文件可能需要数分钟 + - 具体时间取决于文件大小和复杂度 +3. **错误处理**：如果 `file_status` 为 `failed`，查看 `error_message` 字段了解失败原因 +4. **时间格式**：所有时间均为 UTC 时间，格式为 `YYYY-MM-DDTHH:MM:SS.ffffff+0000` +5. **文件顺序**：`files` 数组中的顺序与提交时的顺序一致 + +### 使用流程示例 + +```bash +# 步骤1: 提交任务 +JOB_ID=$(curl -X POST "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/pipeline" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -d '{"file_urls": ["http://example.com/file.pdf"], "file_names": [], "steps": [{"node": "ParseNode", "parameters": {}}]}' \ + | jq -r '.data.job_id') + +echo "Job ID: $JOB_ID" + +# 步骤2: 等待几秒 +sleep 5 + +# 步骤3: 查询任务状态 +curl -X GET "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/v1/genai/jobs/$JOB_ID" \ + -H "moi-key: YOUR_API_KEY" \ + | jq '.' + +# 步骤4: 根据 status 决定是否继续轮询 +# 如果 status 为 "completed"，任务完成 +# 如果 status 为 "processing"，继续等待并查询 +``` + +--- + +## 获取处理结果 + +### 基本信息 + +- **API 地址**: `https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/any/files/{file_id}/raws` +- **请求方法**: `GET` +- **请求格式**: URL 路径参数 +- **响应格式**: `application/zip` + +### 请求头 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| Content-Type | String | 建议 | `application/json` | +| moi-key | String | 是 | API 密钥，用于身份验证 | + +### 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| file_id | String | 是 | 文件 ID，从查询任务状态 API 返回的 `data.files[].file_id` 获取 | + +### 响应说明 + +**成功响应：** + +返回一个 **ZIP 压缩包**，包含文件处理后的所有结果数据。 + +**ZIP 包内容结构：** + +``` +{file_name}-{file_id}/ +├── {file_name}_parse.json # 解析结果的JSON数据 +├── {file_name}.md # 提取的Markdown格式文本 +├── tables/ # 提取的表格（HTML格式） +│ ├── {table_id_1}.html +│ ├── {table_id_2}.html +│ └── ... +└── images/ # 提取的图片 + ├── {image_hash_1}.jpg + ├── {image_hash_2}.jpg + └── ... +``` + +**文件说明：** + +| 文件/目录 | 说明 | +|----------|------| +| `{file_name}_parse.json` | 结构化的解析结果，包含文档的完整解析数据 | +| `{file_name}.md` | 提取的文本内容，Markdown 格式，便于阅读 | +| `tables/*.html` | 文档中的表格，每个表格一个 HTML 文件 | +| `images/*.jpg` | 文档中的图片，以内容哈希命名 | + +### 请求示例 + +**示例 1：下载处理结果** + +```bash +curl -X GET "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/any/files/019ad8c4-cf7e-75ca-afa1-5bd971ff9ed9/raws" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR-MOI-KEY" \ + -o result.zip +``` + +**说明：** + +- 使用 `-o result.zip` 将响应保存为 ZIP 文件 +- `file_id` 来自查询任务状态 API 的响应 +- 下载完成后可以解压查看结果 + +**示例 2：下载并解压** + +```bash +# 1. 下载结果 +curl -X GET "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/any/files/019ad8c4-cf7e-75ca-afa1-5bd971ff9ed9/raws" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -o result.zip + +# 2. 解压文件 +unzip result.zip + +# 3. 查看解压内容 +ls -R +``` + +**示例 3：查看 ZIP 包内容** + +```bash +curl -s -X GET "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/any/files/019ad8c4-cf7e-75ca-afa1-5bd971ff9ed9/raws" \ + -H "Content-Type: application/json" \ + -H "moi-key: YOUR_API_KEY" \ + -o result.zip && unzip -l result.zip +``` + +### 响应示例 + +**ZIP 包内容列表示例：** + +``` +Archive: result.zip + Length Date Time Name +--------- ---------- ----- ---- + 4463 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../2112205248_方佳俊_检测简明报告.pdf_parse.json + 940 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../tables/60d46443-0cec-4556-bf7d-bbff5812f9f5.html + 784 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../tables/3fef6f19-af8c-4791-b18f-a2747af88fa0.html + 3222 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../2112205248_方佳俊_检测简明报告.pdf.md + 33287 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../images/21ec307c62a48eecbc5f24cedd92eee95706024ab5f041cd17a463e78c377b2f.jpg + 38704 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../images/d0be52c9d88f4fe0f7a092863de5679e624a4529552fb863f0d1cdd5ff4fd7cc.jpg + 44015 12-01-2025 07:37 2112205248_方佳俊_检测简明报告.pdf-019ad8cb-.../images/de217bbf2728e9979cf88d0fc7a81ae5adb5695a329a9ad1863eb079dfd22c22.jpg +--------- ------- + 125415 7 files +``` + +**解压后的文件结构示例：** + +``` +2112205248_方佳俊_检测简明报告.pdf-019ad8cb-3861-795c-99a6-03bdc37215ee/ +├── 2112205248_方佳俊_检测简明报告.pdf_parse.json (4.4 KB) +├── 2112205248_方佳俊_检测简明报告.pdf.md (3.2 KB) +├── tables/ +│ ├── 60d46443-0cec-4556-bf7d-bbff5812f9f5.html (940 B) +│ └── 3fef6f19-af8c-4791-b18f-a2747af88fa0.html (784 B) +└── images/ + ├── 21ec307c62a48eecbc5f24cedd92eee95706024ab5f041cd17a463e78c377b2f.jpg (33 KB) + ├── d0be52c9d88f4fe0f7a092863de5679e624a4529552fb863f0d1cdd5ff4fd7cc.jpg (38 KB) + └── de217bbf2728e9979cf88d0fc7a81ae5adb5695a329a9ad1863eb079dfd22c22.jpg (44 KB) +``` + +### 注意事项 + +1. **file_id 来源**: 必须先调用查询任务状态 API 获取 `file_id` +2. **任务状态**: 建议在任务状态为 `completed` 后再获取结果 +3. **文件大小**: ZIP 包大小取决于原文件内容，可能包含大量图片 +4. **内容完整性**: ZIP 包包含 ParseNode 处理的所有输出结果 +5. **文件命名**: 图片使用内容哈希命名，确保唯一性 +6. **保存位置**: 使用 `-o` 参数指定保存的文件名和路径 +7. **多文件任务**: 如果一个任务包含多个文件，需要分别用各自的 `file_id` 获取结果 diff --git a/docs/MatrixOne-Intelligence/workflow api/data_explore_api.md b/docs/MatrixOne-Intelligence/workflow api/data_explore_api.md deleted file mode 100644 index 8e873525..00000000 --- a/docs/MatrixOne-Intelligence/workflow api/data_explore_api.md +++ /dev/null @@ -1,1053 +0,0 @@ -# 数据探索相关 API - -## 源数据卷 - -### 创建源数据卷 - -``` -POST /CreateOriginVolume -``` - -**输入参数：** - -| 参数 | 是否必填 |含义| -| --------------- | ---- | ---- | -| name |是 | 源数据卷名 | - -**示例：** - -```python -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/CreateOriginVolume" - -headers = { - "moi-key": "xxxxx" -} - -body = { - "name": "b_vol3" - -} -response = requests.post(url, json=body, headers=headers) -print(response.json()) -``` - -返回： - -```json -{ - "code": "OK", - "msg": "OK" -} -``` - -### 查看源数据卷列表 - -``` -POST /DescribeOriginVolumes -``` - -**输出参数：** - -| 参数 | 含义 | -| --------------- | ---- | -| id | 卷 id | -| name | 卷名 | -| size | 卷大小 | -| file_num | 文件数量 | - -**示例：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/DescribeOriginVolumes" -headers = { - "moi-key": "xxxxx" -} - -response = requests.post(url, headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -返回： - -```bash -Response Body: { - "code": "OK", - "msg": "OK", - "data": { - "total": 2, - "volumes": [ - { - "id": "YOUR_VOLUME_ID_1", - "name": "b-vol1", - "size": 6787457, - "file_num": 1, - "owner": "YOUR_USERNAME", - "created_at": 1739261047, - "updated_at": 1739261047 - }, - { - "id": "YOUR_VOLUME_ID_2", - "name": "b-vol2", - "size": 40724742, - "file_num": 6, - "owner": "YOUR_USERNAME", - "created_at": 1739345595, - "updated_at": 1739345595 - } - ] - } -} -``` - -### 查看某个源数据卷（文件列表） - -``` -POST /DescribeOriginVolume -``` - -**输出参数：** - -| 参数 | 含义 | -| --------------- | ---- | -| id | 文件 id | -| name | 文件名 | -| type |文件类型 | -| status | 文件解析状态 | -| path | 文件路径 | - -**示例：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/DescribeOriginVolume" -headers = { - "moi-key": "xxxxx" -} - -body={ - "id": "YOUR_VOLUME_ID" -} - -response = requests.post(url, headers=headers,json=body) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -返回： - -```bash -Response Body: { - "code": "OK", - "msg": "OK", - "data": { - "total": 1, - "items": [ - { - "id": "YOUR_FILE_ID", - "name": "红楼梦(通行本)简体横排.pdf", - "type": 2, - "status": 5, - "size": 6787457, - "update_time": 1739261640, - "other_metadata": "", - "reason": "", - "user": "YOUR_USERNAME", - "start_time": 1739261063, - "end_time": 1739261640, - "path": "/YOUR_VOLUME_NAME/红楼梦(通行本)简体横排.pdf" - } - ] - } -} -``` - -### 下载某个源数据卷中的文件 - -``` -POST /GetOriginVolumeFileLink -``` - -**输入参数：** - -| 参数 | 是否必填 |含义| -| --------------- | ---- | ---- | -| volume_id |是 | 源数据卷 id| -| file_id |是 | 文件 id| - -**示例：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/GetOriginVolumeFileLink" -headers = { - "moi-key": "xxxxx" -} - -body = { - "volume_id": "YOUR_VOLUME_ID", - "file_id": "YOUR_FILE_ID" - -} - -response = requests.post(url, headers=headers,json=body) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -返回： - -```bash -Response Body: { - "code": "OK", - "msg": "OK", - "data": { - "link": "YOUR_OSS_BUCKET_FILE_LINK" - } -} -``` - -### 删除某个源数据卷中的某个文件 - -``` -POST /DeleteOriginVolumeFiles -``` - -**输入参数：** - -| 参数 | 是否必填 |含义| -| --------------- | ---- | ---- | -| volume_id |是 | 源数据卷 id| -| file_ids |是 | 文件 id| - -**示例：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/DeleteOriginVolumeFiles" - -headers = { - "moi-key": "xxxxx" -} - - -body={ - "volume_id": "YOUR_VOLUME_ID", - "file_ids": ["YOUR_FILE_ID_1", "YOUR_FILE_ID_2"] -} - - -response = requests.post(url, headers=headers,json=body) - -if response.status_code == 200: - print(response.json()) -else: - print(f"请求失败，状态码：{response.status_code}, 错误信息：{response.text}") -``` - -返回： - -```json -{ - "code": "OK", - "msg": "OK", - "data": {} -} -``` - -## 处理数据卷 - -### 创建处理数据卷 - -``` -POST /byoa/api/v1/explore/volumes -``` - -**Body 输入参数：** - -| 参数 | 是否必填 | 类型 | 含义 | 默认值 | -| ---------------- | -------- | ------ | ----------- | ------ | -| name | 是 | string | 数据卷名称 | | -| parent_volume_id | 否 | string | 处理数据卷 ID | "" | - -**Body 示例：** - -```json -{ - "name": "my-new-volume", - "parent_volume_id": "optional_parent_id_here" -} -``` - -**示例 (Python)：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes" - -headers = { - "moi-key": "xxxxx" -} - -body = { - "name": "b_vol3" - -} -response = requests.post(url, json=body, headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "id": "YOUR_PROCESSED_VOLUME_ID", - "name": "b_vol3", - "created_at": "2025-02-13T11:44:36", - "updated_at": "2025-02-13T11:44:36" - } -} -``` - -**输出参数：** - -| 参数 | 类型 | 含义 | -| ---------- | ------ | ---------- | -| id | string | 数据卷 ID | -| name | string | 数据卷名称 | -| created_at | string | 创建时间 | -| updated_at | string | 更新时间 | - -### 查看处理数据卷列表 - -``` -GET /byoa/api/v1/explore/volumes -``` - -**Query 参数：** - -| 参数 | 是否必填 | 类型 | 含义 | -| -------------- | -------- | ------- | -------------------------------- | -| workflow_using | 否 | boolean | 是否仅列出工作流正在使用的数据卷 | - -**示例 (Python)：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes" -headers = { - "moi-key": "xxxxx" -} -params = { - "workflow_using": False -} -response = requests.get(url, headers=headers, params=params) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "total": 2, - "volumes": [ - { - "name": "example-volume-1", - "created_at": "2025-02-11T16:06:55Z", - "updated_at": "2025-02-11T16:06:55Z", - "user_id": "your_user_id", - "id": "YOUR_PROCESSED_VOLUME_ID_1", - "parent_volume_id": "" - }, - { - "name": "example-volume-2", - "created_at": "2025-02-13T11:44:36Z", - "updated_at": "2025-02-13T11:44:36Z", - "user_id": "your_user_id", - "id": "YOUR_PROCESSED_VOLUME_ID_2", - "parent_volume_id": "YOUR_PARENT_VOLUME_ID" - } - ] - } -} -``` - -**输出参数：** - -| 参数 | 类型 | 含义 | -| ------- | ------------------- | ---------- | -| total | integer | 数据卷总数 | -| volumes | array[TargetVolume] | 数据卷列表 | - -* **TargetVolume** 对象结构:** - - | 参数 | 类型 | 含义 | - | ---------------- | ------ | ---------------------- | - | id | string | 数据卷 ID | - | name | string | 数据卷名称 | - | created_at | string | 创建时间 (ISO 8601) | - | updated_at | string | 更新时间 (ISO 8601) | - | user_id | string | 用户 ID | - | parent_volume_id | string | 处理数据卷 ID (可能为空) | - -### 查看分支处理数据卷列表 - -``` -GET /byoa/api/v1/explore/volumes/{vid} -``` - -**路径参数：** - -* **vid** (string, 必填): 处理数据卷 ID - -**示例 (Python)：** - -```python -import requests -import json - -# 将 {vid} 替换为实际的处理数据卷 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}" -headers = { - "moi-key": "xxxxx" -} -response = requests.get(url.replace("{vid}", "actual_parent_volume_id"), headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** -返回结构与 "查看数据卷列表" 相同，但 **volumes** 列表将只包含指定 **{vid}** 的分支卷。 - -**输出参数：** -与 "查看数据卷列表" 的输出参数一致。 - -### 查看分支处理数据卷内文件列表 - -``` -POST /byoa/api/v1/explore/volumes/{vid}/files -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID - -**Body 输入参数 (可选)：** - -| 参数 | 类型 | 含义 | 默认值 | -| ------- | ----------------- | -------- | ------ | -| filters | object (**Filter**) | 过滤器 | | -| sorter | object (**Sorter**) | 排序器 | | -| offset | integer | 偏移量 | 0 | -| limit | integer | 每页数量 | 30 | - -* **Filter** 对象结构:** - - | 参数 | 类型 | 含义 | - | -------------- | -------------- | -------------- | - | types | array[integer] | 文件类型过滤 | - | status | array[integer] | 文件状态过滤 | - | exclude_status | array[integer] | 排除的文件状态 | - -* **Sorter** 对象结构：** - - | 参数 | 类型 | 含义 | 默认值 | - | ------- | ------- | -------- | ------ | - | sort_by | string | 排序字段 | | - | is_desc | boolean | 是否降序 | true | - -**Body 示例：** - -```json -{ - "filters": { - "types": [2, 3], - "status": [2] - }, - "sorter": { - "sort_by": "updated_at", - "is_desc": true - }, - "offset": 0, - "limit": 10 -} -``` - -**示例 (Python)：** - -```python -import requests -import json - -# 将 {vid} 替换为实际的数据卷 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files" -headers = { - "moi-key": "xxxxx" -} -body = { # 可选 - "limit": 5 -} - -response = requests.post(url.replace("{vid}", "YOUR_PROCESSED_VOLUME_ID"), json=body, headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "total": 1, - "items": [ - { - "id": "YOUR_FILE_ITEM_ID", - "created_at": "2025-02-12T17:46:16.000000+0000", - "updated_at": "2025-02-12T17:51:21.000000+0000", - "user_id": "YOUR_USER_ID", - "priority": 300, - "source_volume_id": "YOUR_SOURCE_VOLUME_ID", - "source_file_id": "YOUR_SOURCE_FILE_ID", - "target_volume_id": "YOUR_TARGET_VOLUME_ID", - "file_name": "红楼梦 (通行本) 简体横排.pdf", - "file_type": 2, - "file_size": 6787457, - "file_path": "YOUR_USER_ID/YOUR_SOURCE_VOLUME_NAME/YOUR_SOURCE_FILE_ID/红楼梦 (通行本) 简体横排.pdf", - "file_status": 2, - "workflow_meta_id": "YOUR_WORKFLOW_META_ID", - "workflow_branch_id": null, - "job_id": "YOUR_JOB_ID", - "error_message": "", - "duration": 300, - "start_time": "2025-02-12T17:46:20.000000+0000", - "end_time": "2025-02-12T17:51:21.000000+0000", - "delete_status": 0 - } - ] - } -} -``` - -**输出参数：** - -| 参数 | 类型 | 含义 | -| ----- | ------------- | -------- | -| total | integer | 文件总数 | -| items | array[**File**] | 文件列表 | - -* **File** 对象结构:** - - | 参数 | 类型 | 含义 | 默认值 | - | ------------------ | ------- | ---------------------- | ------------ | - | id | string | 文件 ID | | - | created_at | string | 创建时间 (ISO 格式) | | - | updated_at | string | 更新时间 (ISO 格式) | | - | user_id | string | 用户 ID (DC 用户) | "dc_user_id" | - | priority | integer | 优先级 | 300 | - | source_volume_id | string | 源数据卷 ID | | - | source_file_id | string | 源文件 ID | | - | target_volume_id | string | 目标数据卷 ID | | - | file_name | string | 文件名 | | - | file_type | integer | 文件类型 | | - | file_size | integer | 文件大小 (bytes) | | - | file_path | string | 文件路径 | | - | file_status | integer | 文件状态 | | - | workflow_meta_id | string | 工作流元数据 ID (可选) | null | - | workflow_branch_id | string | 工作流分支 ID (可选) | null | - | job_id | string | 作业 ID (可选) | null | - | error_message | string | 错误信息 (可选) | null | - | duration | integer | 处理时长 (秒，可选) | 0 | - | start_time | string | 开始处理时间 (可选) | null | - | end_time | string | 结束处理时间 (可选) | null | - | delete_status | integer | 删除状态 (0-未删除) | 0 | - -### 删除分支处理数据卷内文件 - -``` -DELETE /byoa/api/v1/explore/volumes/{vid}/files/{fid} -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID -* **fid** (string, 必填): 文件 ID - -**示例 (Python)：** - -```python -import requests - -# 将 {vid} 和 {fid} 替换为实际的 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files/{fid}" -headers = { - "moi-key": "xxxxx" -} -response = requests.delete(url.replace("{vid}", "actual_volume_id").replace("{fid}", "file_id_to_delete"), headers=headers) - -if response.status_code == 200: - try: - print("Response Body:", response.json()) - except requests.exceptions.JSONDecodeError: - print("Success with empty response body.") -else: - print(f"请求失败，状态码：{response.status_code}, 错误信息：{response.text}") -``` - -**返回：** -成功时 HTTP 状态码为 200。 - -### 获取分支处理数据卷文件解析内容 - -``` -GET /byoa/api/v1/explore/volumes/{vid}/files/{fid}/raws -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID -* **fid** (string, 必填): 文件 ID - -**Query 参数：** - -| 参数 | 是否必填 | 类型 | 含义 | 默认值 | -| --------------- | -------- | ------- | ------------------ | ------ | -| need_embeddings | 否 | boolean | 是否需要 embedding | false | - -**示例 (Python)：** - -```python -import requests -import json - -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files/{fid}/raws" -headers = { - "moi-key": "xxxxx" -} -params = { - "need_embeddings": False # 或者 True -} - -response = requests.get(url.replace("{vid}", "actual_volume_id").replace("{fid}", "actual_file_id"), headers=headers, params=params) - -if response.status_code == 200: - # 从 Content-Disposition 获取文件名，如果没有则使用 file_id - filename = file_id + ".zip" - content_disposition = response.headers.get('Content-Disposition') - if content_disposition: - import re - matches = re.findall("filename=(.+)", content_disposition) - if matches: - filename = matches[0].strip('"') - if not filename.endswith('.zip'): - filename += '.zip' - - # 保存文件 - output_file = os.path.join(data_dir, filename) - with open(output_file, 'wb') as f: - f.write(response.content) - print(f"\n内容已保存到文件：{output_file}") - print(f"文件大小：{len(response.content)} 字节") -else: - print("获取失败！") - print("错误信息：", response.text) -``` - -**返回：** -成功响应为 200。 - -### 获取文件关联的作业信息 - -``` -GET /byoa/api/v1/explore/volumes/{vid}/files/{fid}/jobs -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID -* **fid** (string, 必填): 文件 ID - -**示例 (Python)：** - -```python -import requests -import json - -# 将 {vid} 和 {fid} 替换为实际的 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files/{fid}/jobs" -headers = { - "moi-key": "xxxxx" -} -response = requests.get(url.replace("{vid}", "actual_volume_id").replace("{fid}", "actual_file_id"), headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "job": { - "id": "YOUR_JOB_ID", - "workflow_name": "Associated Workflow", - "status": 2, - "start_time": "2025-02-13T12:00:00Z", - "end_time": "2025-02-13T12:05:00Z" - } - } -} -``` - -**输出参数：** - -| 参数 | 类型 | 含义 | -| ---- | ------ | ------------------------------------------------------------ | -| job | object | 文件关联的作业信息对象。具体结构需要参照实际 API 返回或更详细的定义。 | - -### 获取文件解析的数据块 - -``` -POST /byoa/api/v1/explore/volumes/{vid}/files/{fid}/blocks -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID -* **fid** (string, 必填): 文件 ID - -**Body 输入参数 (`可选)：** - -| 参数 | 类型 | 含义 | 默认值 | -| ------- | ----------------------- | -------- | ------ | -| filters | object (**BlocksFilter**) | 过滤器 | | -| offset | integer | 偏移量 | 0 | -| limit | integer | 每页数量 | 30 | - -* **BlocksFilter** 对象结构:** - - | 参数 | 类型 | 含义 | - | -------------- | ------------- | ---------------------------------------- | - | types | array[string] | 类型过滤 (例如，"text", "image_caption") | - | search_content | string | 内容搜索关键字 | - | block_ids | array[string] | 指定数据块 ID 列表 | - -**Body 示例：** - -```json -{ - "filters": { - "types": ["text"], - "search_content": "MatrixOne" - }, - "limit": 5 -} -``` - -**示例 (Python)：** - -```python -import requests -import json - -# 将 {vid} 和 {fid} 替换为实际的 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files/{fid}/blocks" -headers = { - "moi-key": "xxxxx" -} -body = { - "limit": 2 -} -response = requests.post(url.replace("{vid}", "actual_volume_id").replace("{fid}", "actual_file_id"), json=body, headers=headers) -print("Response Body:", json.dumps(response.json(), indent=4, ensure_ascii=False)) -``` - -**返回：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": { - "total": 10, - "items": [ - { - "id": "YOUR_BLOCK_ID_1", - "content": "Matrix Search 利用 Efficient Net 模型对上传的图片进行特征提取...", - "type": "text", - "content_type": "text", - "file_id": "YOUR_FILE_ID", - "description": null, - "created_at": "2025-02-13T03:45:02", - "updated_at": "2025-02-13T03:45:02", - "text_and_image_id": null - }, - { - "id": "YOUR_BLOCK_ID_2", - "content": "![](/image.jpg) 接下来我们会逐个分析...", - "type": "markdown", - "content_type": "text", - "file_id": "YOUR_FILE_ID", - "description": "An image with text", - "created_at": "2025-02-13T03:45:03", - "updated_at": "2025-02-13T03:45:03", - "text_and_image_id": 123 - } - ] - } -} - - -``` - -**输出参数：** - -| 参数 | 类型 | 含义 | -| ----- | ------------------------------ | ---------- | -| total | integer | 数据块总数 | -| items | array[**SampleEmbeddingResult**] | 数据块列表 | - -* **SampleEmbeddingResult** 对象结构:** - - | 参数 | 类型 | 含义 | - | ----------------- | ------- | ------------------------------------------------ | - | id | string | 数据块 ID | - | content | string | 内容 | - | type | string | 数据块类型 (如 "text", "table", "image_caption") | - | content_type | string | 内容 MIME 类型 (实际可能与 block type 更相关) | - | file_id | string | 文件 ID | - | description | string | 描述 (可选) | - | created_at | string | 创建时间 (ISO 格式) | - | updated_at | string | 更新时间 (ISO 格式) | - | text_and_image_id | integer | 图文关联 ID (可选) | - -### 删除文件解析的数据块 - -``` - -DELETE /byoa/api/v1/explore/volumes/{vid}/files/{fid}/blocks - -``` - -**路径参数：** - -* **vid** (string, 必填): 数据卷 ID -* **fid** (string, 必填): 文件 ID - -**Body 输入参数：** - -| 参数 | 是否必填 | 类型 | 含义 | -| ---- | -------- | ------------- | -------------------- | -| ids | 是 | array[string] | 要删除的数据块 ID 列表 | - -**Body 示例：** - -```json -{ - "ids": ["block_id_1_to_delete", "block_id_2_to_delete"] -} -``` - -**示例 (Python)：** - -```python -import requests -import json - -# 将 {vid} 和 {fid} 替换为实际的 ID -url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/explore/volumes/{vid}/files/{fid}/blocks" -headers = { - "moi-key": "xxxxx" -} -body = { - "ids": ["03e927d3-edbe-426c-835a-0f1e4fcc39b6"] -} -response = requests.delete(url.replace("{vid}", "actual_volume_id").replace("{fid}", "actual_file_id"), json=body, headers=headers) - -if response.status_code == 200: - try: - print("Response Body:", response.json()) - except requests.exceptions.JSONDecodeError: - print("Success, typically with an empty response body.") -else: - print(f"请求失败，状态码：{response.status_code}, 错误信息：{response.text}") -``` - -**返回：** -成功时 HTTP 状态码为 204。 - -## 查看工作流中间结果 - -系统会自动将各组件的执行结果保存到数据库的 **debug_results** 表中，您可以通过以下方式查看 Pipeline 组件的中间结果数据，用于开发调试和问题排查。 - -### API 查询 - -``` -GET /byoa/api/v1/debug_results -``` - -**Query 参数：** - -| 参数名 | 类型 | 是否必填 | 描述 | 默认值 | -| ----------------- | ----------------- | -------- | ----------------------- | ------ | -| **workflow_job_id** | string | 否 | 工作流作业 ID | | -| **workflow_branch_id** | string | 否 | 工作流分支 ID | | -| **workflow_meta_id** | string | 否 | 工作流元数据 ID | | -| **component_name** | string | 否 | 组件名称（支持部分匹配） | | -| **file_id** | string | 否 | 文件 ID | | -| **limit** | integer | 否 | 限制返回结果数量 | 50 | - -**示例 (Python)：** - -```python -import httpx -import json -from datetime import datetime -from typing import Optional - -async def query_debug_results( - workflow_job_id: Optional[str] = None, - workflow_branch_id: Optional[str] = None, - workflow_meta_id: Optional[str] = None, - component_name: Optional[str] = None, - file_id: Optional[str] = None, - limit: int = 50, -): - url = "https://freetier-01.cn-hangzhou.cluster.matrixonecloud.cn/byoa/api/v1/debug_results" - params = { - "workflow_job_id": workflow_job_id, - "workflow_branch_id": workflow_branch_id, - "workflow_meta_id": workflow_meta_id, - "component_name": component_name, - "file_id": file_id, - "limit": limit - } - - # 移除 None 值的参数 - params = {k: v for k, v in params.items() if v is not None} - - headers = { - "moi-key": "xxxxx" - } - - async with httpx.AsyncClient() as client: - response = await client.get(url, params=params, headers=headers) - response.raise_for_status() - return response.json() - -# 使用示例 -async def main(): - # 查询特定作业的调试结果 - results = await query_debug_results( - workflow_job_id="your_job_id_here", - limit=20 - ) - print(json.dumps(results, indent=4)) -``` - -**返回示例：** - -```json -{ - "code": "ok", - "msg": "ok", - "data": [ - { - "id": "72f66505-8f26-458b-9621-ef9ce9acf268", - "workflow_branch_id": "82f1064d-49a7-4c18-851d-8a7419090af3", - "workflow_meta_id": "69985cd1-cc08-4be5-adac-4de14a5fc4e0", - "component_name": "EnhancedDOCXToDocument", - "component_results": "{\"documents\": [{\"_type\": \"Document\", \"id\": \"d0f523a6af915a9ad4c6ca017b3ea79e958305902cd366d600298e00bb318b62\", \"content\": \"云原生应用的高可用架构设计...\", \"content_length\": 1540, \"meta\": {...}}]}", - "workflow_job_id": "019742c0-ee10-79b3-902b-41df812d0de1", - "file_id": "019742c0-ee10-79ce-9020-7b266182e431", - "created_at": "2025-06-06T01:00:41", - "updated_at": "2025-06-06T01:00:41" - } - ] -} -``` - -**返回参数说明：** - -1. **基础信息字段** - - **id**: 调试结果记录的唯一标识符 - - **workflow_job_id**: 工作流作业的 ID - - **workflow_branch_id**: 工作流分支的 ID - - **workflow_meta_id**: 工作流元数据的 ID - - **component_name**: 组件名称，例如 "EnhancedDOCXToDocument" - - **file_id**: 处理的文件 ID - - **created_at**: 记录创建时间 - - **updated_at**: 记录更新时间 - -2. **component_results 字段**（JSON 字符串，包含以下结构）： - - **documents**: 文档数组，每个文档包含： - - **_type**: 文档类型，通常为 "Document" - - **id**: 文档的唯一标识符 - - **content**: 文档的实际内容 - - **content_length**: 内容长度 - - **meta**: 元数据对象，包含： - - **content_type**: 内容类型（如 "text"） - - **file_name**: 文件名 - - **file_id**: 文件 ID - - **target_volume_id**: 目标数据卷 ID - - **source_volume_id**: 源数据卷 ID - - **source_file_id**: 源文件 ID - - **job_id**: 作业 ID - - **job_version**: 作业版本 - - **workflow_meta_id**: 工作流元数据 ID - - **workflow_branch_id**: 工作流分支 ID - - **user_id**: 用户 ID - - **docx**: DOCX 特有的元数据（如果是 DOCX 文件） - - **author**: 作者 - - **created**: 创建时间 - - **modified**: 修改时间 - - 其他 DOCX 相关属性 - - **md_file_url**: 生成的 Markdown 文件 URL（如果有） - -通过这个 API，您可以查询工作流中各个组件的处理结果，用于调试和验证工作流的执行情况。每个组件的处理结果都会被记录下来，包括输入文档的处理结果以及相关的元数据信息。 - -### 数据库直接查询 - -如果您有数据库访问权限，也可以直接通过 SQL 查询中间结果： - -```sql --- 查看最近的中间结果 -SELECT component_name, workflow_job_id, created_at -FROM debug_results -ORDER BY created_at DESC LIMIT 20; - --- 按作业 ID 查询特定作业的所有组件结果 -SELECT component_name, component_results, created_at -FROM debug_results -WHERE workflow_job_id = 'your_job_id_here' -ORDER BY created_at ASC; - --- 按组件名称查询 -SELECT workflow_job_id, created_at -FROM debug_results -WHERE component_name = 'PDFConverter' -ORDER BY created_at DESC LIMIT 10; -``` - -注意事项 - -1. 建议使用 **limit** 参数限制查询结果数量，避免返回过多数据 -2. 组件结果以 JSON 格式存储在 **component_results** 字段中 -3. 可以通过组合不同的查询参数来精确定位需要查看的结果 -4. 时间戳使用 UTC 时间 diff --git a/mkdocs.yml b/mkdocs.yml index b449aa08..ff329b20 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,6 +79,7 @@ nav: - MCP 使用说明: MatrixOne-Intelligence/mcp/mcp.md - Deerflow 结合 MOI RAG 服务使用说明: MatrixOne-Intelligence/develop/deerflow.md - API 说明: + - 原子能力 API 说明: MatrixOne-Intelligence/workflow api/automic_api.md - 工作流 API 说明: - 鉴权: MatrixOne-Intelligence/workflow api/token_api.md - 数据接入: MatrixOne-Intelligence/workflow api/data_connect_api.md @@ -87,8 +88,6 @@ nav: - 数据导出: MatrixOne-Intelligence/workflow api/data_export_api.md - 告警: MatrixOne-Intelligence/workflow api/alarm_api.md - 指标: MatrixOne-Intelligence/workflow api/indicator_api.md - - 快速体验 API 说明: - - 结构化抽取: MatrixOne-Intelligence/quick-start api/structured_extraction_api.md - 数据库实例: - MySQL 兼容性: MatrixOne-Intelligence/Overview/mysql-compatibility.md - 管理实例: