文档目录树

SoMark 可以识别文档中的标题层级，并在 JSON 结果的 data.result.catalog 中返回嵌套的目录树。每个目录节点都保留标题内容、标题层级、所在页码和对应内容块编号，可用于构建阅读导航、定位原文，以及按章节切分内容，解决 RAG 固定长度切块易打散章节上下文、难以按主题检索的问题。

场景	推荐方法
正在开发自己的应用或服务	通过解析 API 获取 `data.result.catalog`
已有文档或 SoMark JSON，并使用支持 Skill 的 Agent	使用 `get-catalog-tree` Skill

方法一：通过解析 API 获取

目录树不是单独调用的接口。解析时开启 feature_config.enable_title_level_recognition，并请求 json 输出即可获得。

开启标题层级识别

在解析请求的 feature_config 中将 enable_title_level_recognition 设为 true。该参数默认值为 false。

请求 JSON 输出

将 json 加入 output_formats。解析完成后，从响应的 data.result.catalog 读取目录树。

按需使用目录节点

直接渲染 children 可得到多级导航；使用 page_num 和 block_idx 可将目录项关联到原文页面和内容块。

以下示例使用同步解析接口：

Python

import json
import requests

url = "https://somark.cn/api/v1/parse/sync"
data = {
    "output_formats": ["json"],
    "api_key": "sk-***",
    "feature_config": json.dumps({
        "enable_title_level_recognition": True,
    }),
}

with open("example.pdf", "rb") as file:
    response = requests.post(
        url,
        data=data,
        files={"file": ("example.pdf", file)},
    )

response.raise_for_status()
catalog = response.json()["data"]["result"]["catalog"]
print(json.dumps(catalog, ensure_ascii=False, indent=2))

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append(
  "file",
  new Blob([await readFile("example.pdf")], { type: "application/pdf" }),
  "example.pdf",
);
form.append("output_formats", "json");
form.append("api_key", "sk-***");
form.append("feature_config", JSON.stringify({
  enable_title_level_recognition: true,
}));

const response = await fetch("https://somark.cn/api/v1/parse/sync", {
  method: "POST",
  body: form,
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
console.log(result.data.result.catalog);

<?php
// Requires: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post("https://somark.cn/api/v1/parse/sync", [
    "multipart" => [
        [
            "name" => "file",
            "contents" => fopen("example.pdf", "rb"),
            "filename" => "example.pdf",
        ],
        ["name" => "output_formats", "contents" => "json"],
        ["name" => "api_key", "contents" => "sk-***"],
        [
            "name" => "feature_config",
            "contents" => json_encode([
                "enable_title_level_recognition" => true,
            ]),
        ],
    ],
]);

$result = json_decode($response->getBody(), true);
print_r($result["data"]["result"]["catalog"]);

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

func check(err error) {
    if err != nil {
        panic(err)
    }
}

func main() {
    file, err := os.Open("example.pdf")
    check(err)
    defer file.Close()

    var body bytes.Buffer
    writer := multipart.NewWriter(&body)
    part, err := writer.CreateFormFile("file", filepath.Base(file.Name()))
    check(err)
    _, err = io.Copy(part, file)
    check(err)

    check(writer.WriteField("output_formats", "json"))
    check(writer.WriteField("api_key", "sk-***"))
    check(writer.WriteField(
        "feature_config",
        `{"enable_title_level_recognition":true}`,
    ))
    check(writer.Close())

    request, err := http.NewRequest(
        http.MethodPost,
        "https://somark.cn/api/v1/parse/sync",
        &body,
    )
    check(err)
    request.Header.Set("Content-Type", writer.FormDataContentType())

    response, err := http.DefaultClient.Do(request)
    check(err)
    defer response.Body.Close()

    fmt.Println(response.Status)
    _, err = io.Copy(os.Stdout, response.Body)
    check(err)
}

// Requires: org.apache.httpcomponents.client5:httpclient5
import java.io.File;
import java.nio.charset.StandardCharsets;

import org.apache.hc.client5.http.classic.methods.HttpPost;
import org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.http.ContentType;
import org.apache.hc.core5.http.io.entity.EntityUtils;

public class ParseDocument {
    public static void main(String[] args) throws Exception {
        HttpPost request = new HttpPost(
            "https://somark.cn/api/v1/parse/sync"
        );
        request.setEntity(MultipartEntityBuilder.create()
            .addBinaryBody(
                "file",
                new File("example.pdf"),
                ContentType.APPLICATION_PDF,
                "example.pdf"
            )
            .addTextBody("output_formats", "json")
            .addTextBody("api_key", "sk-***")
            .addTextBody(
                "feature_config",
                "{\"enable_title_level_recognition\":true}",
                ContentType.APPLICATION_JSON
            )
            .build());

        try (
            CloseableHttpClient client = HttpClients.createDefault();
            CloseableHttpResponse response = client.execute(request)
        ) {
            System.out.println(EntityUtils.toString(
                response.getEntity(),
                StandardCharsets.UTF_8
            ));
        }
    }
}

require "json"
require "net/http"
require "uri"

uri = URI("https://somark.cn/api/v1/parse/sync")
request = Net::HTTP::Post.new(uri)

File.open("example.pdf", "rb") do |file|
  request.set_form([
    ["file", file, {
      filename: "example.pdf",
      content_type: "application/pdf"
    }],
    ["output_formats", "json"],
    ["api_key", "sk-***"],
    ["feature_config", JSON.generate({
      enable_title_level_recognition: true
    })]
  ], "multipart/form-data")

  response = Net::HTTP.start(
    uri.hostname,
    uri.port,
    use_ssl: uri.scheme == "https"
  ) { |http| http.request(request) }

  catalog = JSON.parse(response.body).dig("data", "result", "catalog")
  puts JSON.pretty_generate(catalog)
end

有关完整请求参数，请参阅同步解析。

方法二：使用 get-catalog-tree Skill

get-catalog-tree Skill 支持 SoMark 解析接口支持的全部文档格式，包括 PDF、图片、Word、PPT 和 Excel，也可以直接读取 SoMark JSON。你只需把文件交给支持 Skill 的 Agent，即可获得标准嵌套目录 JSON。完整格式列表请参阅支持的文件格式。

目录树依赖明确的标题层级。Excel 等通常以表格数据为主、没有目录结构的文档虽然可以解析，但不建议使用此功能，生成的目录树可能为空或缺少有意义的层级。

首次使用时，任选一种方式安装 Skill：

在 Agent 中安装
使用命令安装

输入以下提示词：

请从 https://github.com/SoMarkAI/skills 安装 get-catalog-tree Skill。

npx skills add SoMarkAI/skills --skill get-catalog-tree

安装后，在 Agent 中输入：

使用 SoMark get-catalog-tree Skill 为 document.pdf 生成目录树 JSON。

如果输入原始文档，Agent 会在发起 SoMark 解析前请求一次确认。Skill 只生成一个文件：

document.catalog.json     # 标准嵌套目录 JSON

也可以直接提供 SoMark JSON：

使用 SoMark get-catalog-tree Skill 读取 result.json，生成嵌套目录树 JSON。

目录节点保留 page_num 和 block_idx，可关联到原始解析 JSON 中对应的标题块，用于后续章节分块和 RAG 处理。也可以直接运行 Skill 自带的脚本：

python <skill-directory>/scripts/get_catalog_tree.py --file document.pdf --output catalog
python <skill-directory>/scripts/get_catalog_tree.py --json result.json --output catalog

响应结构

目录树位于 data.result.catalog，为目录节点数组。顶层节点通常对应文档中的一级标题，子节点通过 children 递归组织。

{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "catalog": [
        {
          "page_num": 0,
          "block_idx": 6,
          "title_level": 1,
          "content": "第一章 引言",
          "children": [
            {
              "page_num": 0,
              "block_idx": 14,
              "title_level": 2,
              "content": "1.1 研究背景",
              "children": []
            }
          ]
        }
      ]
    }
  }
}

字段	类型	说明
`page_num`	integer	标题所在页的页码，从 `0` 开始计数。展示给最终用户时，如需从第 1 页开始计数，可加 `1`。
`block_idx`	integer	标题在该页解析结果中的内容块编号，可用于回查和定位对应内容块。
`title_level`	integer	标题层级。`1` 表示 H1，`2` 表示 H2，依此类推。
`content`	string	标题文本。
`children`	array	当前标题的下一级标题节点；没有子标题时为空数组。

使用建议

目录节点已经是嵌套结构，无需再根据 title_level 手动组装父子关系。
使用目录树进行章节切分时，可将一个节点及其子节点视为同一章节范围；再结合 page_num、block_idx 从 JSON 内容块中取回正文。
标题层级基于文档版式和内容识别。对于原文没有明确标题层次、扫描质量较低或排版不规则的文件，建议在接入前抽样检查结果。
如只需要文档内容，不需要章节导航，可保持该开关关闭，以使用默认解析配置。

产品概览

快速开始

生态集成

拓展功能

常见问题

方法一：通过解析 API 获取

方法二：使用 get-catalog-tree Skill

响应结构

使用建议

​方法一：通过解析 API 获取

​方法二：使用 get-catalog-tree Skill

​响应结构

​使用建议

方法一：通过解析 API 获取

方法二：使用 get-catalog-tree Skill

响应结构

使用建议