# 使用API调用文档解析工作流 在AgentArts平台上开发工作流时，部分业务场景需要工作流具备文档理解能力，例如：合同审核场景中需读取用户上传的合同文件并提取关键条款。 文档理解能力依赖工作流中的插件节点、MCP节点或代码节点等方式实现。工作流支持在开始节点定义File或Array\类型的文档参数，单文档时使用File类型；多文档时使用Array\类型。两种类型的参数构造方式不同，详见后续步骤。 **工作流部署时采用API Key认证，API调用也采用该方法。** 工作流的搭建、参数配置详见[步骤一：搭建文档解析工作流]。 - 工作流本身，支持doc、docx、txt、pdf、csv、xlsx、xls、pptx、ppt。单文件大小限制128MB。 - 用户上传总量：200 MB/24h，同一用户24小时内累计不超过200MB。 - 用户上传次数：20次/5min，同一用户5分钟内最多上传20次。 - 案例中使用的"文件解析"插件，可以解析txt、doc、docx、csv和xlsx类型的文件。文档解析的能力与用户选择的插件或MCP相关。案例的"文件解析"插件一次解析一个，用户上传多个文档时，需要将"文件解析"插件放在工作流循环节点中。 - 待识别的文档请提前上传至OBS服务中，生成的文档链接**需要公网可访问** 。有关OBS（对象存储服务）介绍请参考[OBS快速入门](https://support.huaweicloud.com/qs-obs/obs_qs_0001.html)。 #### 前置检查 - 已开通AgentArts服务。 - 已接入可用模型。调用智能体/工作流API时不支持使用平台赠送的免费token，确保配置的模型满足以下任一条件： - 接入华为云MaaS服务模型并配置模型API Key（平台默认模型来源），操作请参考[接入华为云MaaS服务付费模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0095.html)。 - 已在智能体/工作流中自行对接外部第三方模型，操作请参考[手动接入和使用OpenAI协议模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0096.html)。 未接入MaaS模型且未使用第三方模型时，调用API将返回"Model call failed"报错。 #### 步骤一：搭建文档解析工作流 本案例中使用"文件解析"插件构造一个简单的工作流，该插件一次只能解析一个文档。工作流支持在开始节点定义File或Array\类型的文档参数，File类型对应传1个文档；Array\类型对应传多个文档，传多个文档时，需要将插件放在循环节点中，按照上传的文档数量依次解析。 - **搭建单文档解析工作流** 创建一个任务型工作流，各节点配置如下。 图1单文档解析工作流 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949856.png "点击放大") 表1单文档解析工作流 | 节点 | 配置说明 | |:---|:---| | 开始节点 | 新增一个参数。 - 参数名称：doc - 参数类型：**File/Doc** - 必填：勾选 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717549521.png "点击放大") | | 插件节点 | 添加"文件解析"插件。 file_url参数引用开始节点的doc参数。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687790010.png "点击放大") | | 大模型节点 | - 模型：DeepSeek-V4-Flash - 输出格式：文本，开启流式输出 - 输入参数： - query：引用开始节点的query - doc：引用文件解析节点的content - 输出参数：使用默认的raw_output，不改动 - 系统提示词：不填写 - 用户提示词：根据用户问题{{query}}结合{{doc}}回答问题 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687790040.png "点击放大") | | 结束节点 | 输入参数：result，引用大模型节点的raw_output。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949872.png "点击放大") | - **搭建多文档解析工作流** 创建一个任务型工作流，各节点配置如下。 图2多文档解析工作流 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687790024.png "点击放大") 表2多文档解析工作流 | 节点 | 配置说明 | |:---|:---| | 开始节点 | 新增一个参数。 - 参数名称：doc - 参数类型：**Array\/Doc** - 必填：勾选 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949886.png "点击放大") | | 循环节点 | 循环类型：使用数组循环。 循环数组：使用默认参数，值引用开始节点的doc。 输出参数：output，只引用"文件解析"插件的content（提前将文件解析插件放在循环体内再设置参数）。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717549509.png "点击放大") | | 插件节点 | 添加"文件解析"插件，放在循环体内，并连接循环输入、循环输出。 输入参数：file_url，值引用循环体的item参数。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687790026.png "点击放大") | | 大模型节点 | - 模型：DeepSeek-V4-Flash - 输出格式：文本，开启流式输出 - 输入参数： - query：引用开始节点的query - doc：引用循环节点的output - 输出参数：使用默认的raw_output，不改动 - 系统提示词：不填写 - 用户提示词：根据用户问题{{query}}结合{{doc}}回答问题 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949866.png "点击放大") | | 结束节点 | 输入参数：result，引用大模型节点的raw_output。 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717549499.png "点击放大") | #### 步骤二：部署工作流 **本示例中的工作流部署时采用API Key认证，API调用也采用该方法。** 1. 工作流运行无问题后，单击"提交版本"，需要勾选"部署至实例"选项。勾选后单击"确定"。 图3提交版本 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389643.png "点击放大") 2. 入站身份认证选择"API Key"，并勾选日志记录、指标、调用链。其余配置可以使用默认值。 图4选择入站身份认证 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717549529.png "点击放大") 3. 单击"确定"部署工作流。 #### 步骤三：获取API调用凭证（获取Authorization） 1. 在左侧导航栏中选择"开发中心 \> 智能体管理"，选择需要调用的工作流，并复制ID。 被调用的工作流需要是"已提交"状态。如果显示"未提交"，请单击工作流的名称，进入编辑页面，进行"提交版本"及部署操作。未部署状态的工作流无法获取调用凭证。 图5获取ID ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949876.png "点击放大") 2. 获取ID后，在"部署运行 \> 智能体运行时"页面搜索ID。 图6搜索ID ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389641.png "点击放大") 3. 单击ID名称，进入基本信息页面，找到"访问与权限控制"对应的URN。单击URN名称。 图7单击URN名称 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389611.png "点击放大") 4. 在页面中获取API Key的取值。 获取API Key的值后，在API Key值前加上"Bearer "即为Authorization的值（注意Bearer后有一个空格）。 图8获取API Key取值 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717549519.png "点击放大") #### 步骤四：调用文档解析工作流 **API接口：** POST /runtimes/{runtime_name}/invocations **API接口获取方法：** 1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏中选择"开发中心 \> 智能体管理"，在"工作流"页签选择所需的工作流。 3. 复制调用路径。（注意智能体需要经过发布，显示为"已提交"状态） 图9获取API接口 ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389623.png "点击放大") 工作流支持传入单个文档和多个文档两种调用方式，区别在于开始节点中文档参数的类型选择不同，进而影响API请求体中参数值的构造方式： - **File类型（单文档）**：参数值为文档URL字符串，无需转义。 - **Array\类型（多文档）**：参数值为文档URL数组，多个URL放入数组中。 工作流的文档参数直接作为inputs中的字段传入，文档需先上传至OBS并获取公网可访问的URL，无需像单智能体那样将URL数组序列化后嵌入query字段，因此不存在转义问题。 **方式一：File类型（单文档调用）** 开始节点中文档参数选择File类型。 Python调用示例： ``` import requests import json url = "https://{endpoint}/runtimes/{runtime_name}/invocations" payload = json.dumps({ "inputs": { "doc": "https://obs-url...", "query": "识别文档内容" } }) headers = { 'Content-Type': 'application/json', 'Authorization': '您的Authorization，格式为Bearer {api_key}', 'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、"-"、"_"组成，不超过64位字符。' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` cURL调用示例： 针对不同操作系统，命令的转义和换行符有所不同。 - Windows 在CMD（命令提示符）中执行如下命令： OBS的URL中可能会包含\&字符，Windows CMD会将URL中的\&识别为命令分隔符，导致含签名参数的OBS URL执行报错。可将请求体保存为独立的body.json文件，内容不经过Shell解析。Linux/macOS使用单引号包裹，\&不会被解释，无需此处理。 第一步：将以下内容保存为body.json文件： ``` { "inputs": { "doc": "https://obs-url...", "query": "识别文档内容" } } ``` 第二步：执行以下命令： ``` curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^ --header "Authorization: 您的Authorization，格式为Bearer {api_key}" ^ --header "x-hw-agentarts-session-id: 123456789" ^ --header "Content-Type: application/json" ^ --data @body.json ``` - Linux/macOS 在Terminal（终端）中执行如下命令： ``` curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \ --header 'Authorization: 您的Authorization，格式为Bearer {api_key}' \ --header 'x-hw-agentarts-session-id: 123456789' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": { "doc": "https://obs-url...", "query": "识别文档内容" } }' ``` **方式二：** **Array\类型（多文档调用）** 开始节点中文档参数选择Array\类型。 Python调用示例： ``` import requests import json url = "https://{endpoint}/runtimes/{runtime_name}/invocations" payload = json.dumps({ "inputs": { "doc": [ "https://obs-urlfile1...", "https://obs-urlfile2..." ], "query": "识别文档内容" } }) headers = { 'Content-Type': 'application/json', 'Authorization': '您的Authorization，格式为Bearer {api_key}', 'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、"-"、"_"组成，不超过64位字符。' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` cURL调用示例： 针对不同操作系统，命令的转义和换行符有所不同。 - Windows 在CMD（命令提示符）中执行如下命令： OBS的URL中可能会包含\&字符，Windows CMD会将URL中的\&识别为命令分隔符，导致含签名参数的OBS URL执行报错。可将请求体保存为独立的body.json文件，内容不经过Shell解析。Linux/macOS使用单引号包裹，\&不会被解释，无需此处理。 第一步：将以下内容保存为body.json文件： ``` { "inputs": { "doc": [ "https://obs-urlfile1...", "https://obs-urlfile2..." ], "query": "识别文档内容" } } ``` 第二步：执行以下命令： ``` curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^ --header "Authorization: 您的Authorization，格式为Bearer {api_key}" ^ --header "x-hw-agentarts-session-id: 123456789" ^ --header "Content-Type: application/json" ^ --data @body.json ``` - Linux/macOS 在Terminal（终端）中执行如下命令： ``` curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \ --header 'Authorization: 您的Authorization，格式为Bearer {api_key}' \ --header 'x-hw-agentarts-session-id: 123456789' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": { "doc": [ "https://obs-urlfile1...", "https://obs-urlfile2..." ], "query": "识别文档内容" } }' ```