> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 FastGPT 中使用 SoMark

> 通过 FastGPT 工具节点将「SoMark 文档解析」接入工作流

## 在工作流中使用 SoMark 文档解析工具

<Steps>
  <Step title="添加 SoMark 文档解析节点">
    在 FastGPT 应用编排中添加 **SoMark 文档解析** 节点。

    <img src="https://mintcdn.com/soulcode-aa7e5a93/mqnfzKMhfEvy3I3O/images/fastgpt-%E6%B7%BB%E5%8A%A0%E6%8F%92%E4%BB%B6.png?fit=max&auto=format&n=mqnfzKMhfEvy3I3O&q=85&s=f5d2b86daa3a97ba7fff7d44152d0b66" alt="fastgpt-添加插件" width="1798" height="984" data-path="images/fastgpt-添加插件.png" />
  </Step>

  <Step title="激活 SoMark 文档解析工具">
    点击**去激活**，填写密钥配置：

    * **Base URL**：使用 SoMark API 时填写 `https://somark.tech/api/v1`; 私有化部署时填写本地部署的 Base URL。
    * **API Key**：使用 SoMark API 时填写；私有化部署无需填写。

    <Note>
      还没有 API Key？[前往 SoMark API 工作台获取 API Key](https://somark.tech/workbench/apikey)。免费额度无需领取，会自动发放到账户（每日 500 页、每月 2000 页）。
    </Note>

    <Warning>
      使用 **SoMark Self-host** 时，插件会在 **Base URL** 后自动拼接对应接口路径。请填写能命中自建服务 API 前缀的位置，不要追加具体接口路径。
    </Warning>

    <img src="https://mintcdn.com/soulcode-aa7e5a93/rxyqA7fo56mP0TxQ/images/fastgpt-%E6%BF%80%E6%B4%BB%E6%8F%92%E4%BB%B6.png?fit=max&auto=format&n=rxyqA7fo56mP0TxQ&q=85&s=a86e9f6284f5d2bbd3ec5077b3f42cdf" alt="fastgpt-激活插件" width="962" height="846" data-path="images/fastgpt-激活插件.png" />
  </Step>

  <Step title="搭建最小演示">
    用一个文件输入节点连接 **SoMark 文档解析** 的 **文件** 参数，再把解析结果输出传给下游节点。该插件一次可解析多个文件，适合接收用户上传的 PDF、图片、Word、PPT 或 Excel 文件。

    <img src="https://mintcdn.com/soulcode-aa7e5a93/rxyqA7fo56mP0TxQ/images/fastgpt-%E6%9E%84%E5%BB%BA%E5%B7%A5%E4%BD%9C%E6%B5%81.png?fit=max&auto=format&n=rxyqA7fo56mP0TxQ&q=85&s=ffe937ca5c886df8ce812f85e89afec5" alt="fastgpt-构建工作流" width="2044" height="952" data-path="images/fastgpt-构建工作流.png" />

    在调试或预览中上传文件并运行工作流。节点会按输入顺序为每个文件返回一项结果，每项包含 `markdown`、`json` 和 `error` 字段，你可以在下游节点按需引用。

    <img src="https://mintcdn.com/soulcode-aa7e5a93/mqnfzKMhfEvy3I3O/images/fastgpt-%E8%BF%90%E8%A1%8C%E9%A2%84%E8%A7%88.png?fit=max&auto=format&n=mqnfzKMhfEvy3I3O&q=85&s=7d2d66ce24821cdc338e9016ecb31f45" alt="fastgpt-运行预览" width="878" height="1442" data-path="images/fastgpt-运行预览.png" />
  </Step>
</Steps>

***

## 插件参数与输出

### 输入参数

| 参数      | 类型   | 必填 | 默认值                | 说明                                             |
| ------- | ---- | -- | ------------------ | ---------------------------------------------- |
| 文件      | 文件选择 | ✅  | 无                  | 待解析文件。一次可选择多个文件，支持 PDF、图片、Word、PPT 和 Excel 文件。 |
| 输出格式    | 多选   | -  | `JSON`, `Markdown` | 选择返回 `JSON`、`Markdown`，或同时返回两种格式。              |
| 图片格式    | 单选   | -  | `URL`              | 图片元素返回格式，支持 `URL`、`Base64`、`None`。             |
| 公式格式    | 单选   | -  | `LaTeX`            | 公式元素返回格式，支持 `LaTeX`、`MathML`、`ASCII`。          |
| 表格格式    | 单选   | -  | `HTML`             | 表格元素返回格式，支持 `HTML`、`Markdown`、`Image`。         |
| 化学结构式格式 | 单选   | -  | `Image`            | 化学结构式元素返回格式，当前仅支持 `Image`。                     |
| 文字跨页拼接  | 开关   | -  | `关闭`               | 将跨页文字段合并为连续段落。                                 |
| 表格跨页拼接  | 开关   | -  | `关闭`               | 将跨页表格合并为完整表格。                                  |
| 标题层级识别  | 开关   | -  | `关闭`               | 识别 H1、H2、H3 等标题层级。                             |
| 文中图     | 开关   | -  | `关闭`               | 返回文字段落中的图片。                                    |
| 表格图     | 开关   | -  | `开启`               | 返回表格单元格内的图片。                                   |
| 图片理解    | 开关   | -  | `开启`               | 对文档内图片进行语义理解和结构化描述。                            |
| 保留页眉页脚  | 开关   | -  | `关闭`               | 开启后保留页眉页脚内容。                                   |

### 输出变量

| 变量   | 类型    | 说明                                                        |
| ---- | ----- | --------------------------------------------------------- |
| 解析结果 | array | 每个输入文件对应一个结果，按输入顺序返回。每项包含 `markdown`、`json` 和 `error` 字段。 |

#### 结果字段

| 字段         | 类型     | 说明                                          |
| ---------- | ------ | ------------------------------------------- |
| `markdown` | string | Markdown 格式全文。未选择 `Markdown` 输出或解析失败时为空字符串。 |
| `json`     | object | JSON 格式解析结果。未选择 `JSON` 输出或解析失败时为空对象。        |
| `error`    | string | 当前文件的错误信息。解析成功时为空字符串。                       |

## 注意事项

* FastGPT 文件选择器传入的是文件下载 URL，工具会先下载文件，再发送到 SoMark 解析服务。
* 如果文件 URL 带有 `filename` 查询参数，工具会优先使用该文件名，避免临时下载地址丢失 `.pdf`、`.docx` 等后缀导致文件类型误判。