# @docling/docling-client 中文文档

规范地址：https://npmcn.com/package/%40docling/docling-client/

版本：2\.150\.0
npm 元数据更新时间：2026-11-11T07:51:43.163Z
中文译文更新时间：2026-11-12T14:03:02.188Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40docling/docling-client
原文对照：https://npmcn.com/package/%40docling/docling-client/?lang=original
项目主页：https://github.com/docling-project/docling-ts/tree/main/docling-client
源码仓库：https://github.com/docling-project/docling-ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-07-31T11:29:51.364Z
- 最新版本发布：2026-11-11T07:51:42.577Z
- 近 30 天下载量：4966（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

用于 Docling Service 和用于 IBM Watsonx 的 Docling 脚本客户端 .

## 安装

```sh
npm install @docling/docling-client
```

也可以使用：`pnpm add @docling/docling-client`、`yarn add @docling/docling-client`、`bun add @docling/docling-client`

## README

# 调试客户端

`@docling/docling-client` 是 TypeScript 的正式客户端 [导航服务](https://github.com/docling-project/docling-serve) 管理 实施相同API的道克服务,包括IBM主持道克.

这是一个远程客户端。 文档转换、OCR、取表、浓缩、, 在服务中进行分解;软件包提交工作,遵循任务状态, 检索结果,安全地实现文物.

## 安装

```sh
npm install @docling/docling-client
```

需要18号节点或更新。 URL和 Base64 请求在节点和 浏览器. 节点额外支持本地路径. 使用 默认预签名的艺术路径必须提供可信任的 DNS 解析器 `artifactDownload.resolver`,或明确选择使用 `allowPrivateUrls`; 浏览器不披露默认所需的 DNS 答案 SSRF检查.

## 配置

```ts
import { DoclingClient } from '@docling/docling-client';

const client = new DoclingClient({
  baseUrl: process.env.DOCLING_URL!,
  apiKey: process.env.DOCLING_API_KEY,
  options: {
    do_ocr: true,
    table_mode: 'accurate',
  },
  statusWatcher: 'websocket',
  webSocketFallbackToPoll: true,
  jobTimeoutMs: 15 * 60_000,
  maxConcurrency: 8,
  httpRetries: 3,
  httpTimeoutMs: 60_000,
});
```

基础 URL 是服务根, 不 `/v1`,询问,或碎片. `X-Api-Key` 于 `apiKey` 已经设定。 逐个调用服务头覆盖 构造器头.

## 转换

`convert()` 是高级的,Python相容的路径。 它尝试一个预先签名 文物目标首先, 微小地回落到 内部结果 当文物 无法存储, 默认情况下请求 Markdown 加上 Docling JSON,以及 返回 a `ConversionResult`。 。 。 .

```ts
const result = await client.convert('https://example.org/manual.pdf', {
  options: {
    do_ocr: true,
    table_mode: 'accurate',
    include_images: true,
  },
  maxNumPages: 100,
  maxFileSize: 100 * 1024 * 1024,
  pageRange: [1, 20],
  raisesOnError: true,
});

console.log(result.status);
console.log(result.document);
console.log(result.errors);
```

高级别电话接受的资料来源是:

-   HTTP( S) URL 字符串, `URL`,或 `{kind: "http"}` 来源,包括 源头指针;
-   节点文件系统路径;
-   `{data, filename, contentType}` 使用 `Blob`, (中文(简体) ), `ArrayBuffer`,或输入数组;
-   基础64 `{kind: "file", filename, base64_string}` 来源.

ZIP URL在普通的转换路径被拒绝. 本地和二进制输入 使用多段上传进行内置,ZIP,以及预署目标. 外部目标 使用统一的基数64请求,因此其完整的证书和坐标 被保留下来.

`convertAll()` 懒散地运行着每个源头一个完整的任务 货币, 保存输入顺序, 并将单个失败变为失败 `ConversionResult` 在不中断不相关的工作的情况下, 值 :

```ts
for await (const result of client.convertAll(urls, {
  maxConcurrency: 16,
})) {
  console.log(result.input.filename, result.status);
}
```

## 提交任务并选择目标

`submitSource()` 镜像 Python 面向工作 `submit()`2\. 方便方法 可用于 URL、 base64 和 二进制输入.

```ts
const job = await client.submitUrl(
  'https://example.org/manual.pdf',
  { to_formats: ['md', 'json'] },
  { target: { kind: 'inbody' } }
);

for await (const status of job.watch()) {
  console.log(status.task_status, status.task_position);
}

const result = await job.result();
console.log(result.document);
```

具体目标成果静态输入:

| 目标 | 结果 |
| --- | --- |
| 删除 | 预先签名的答复,或 `ConversionResult` 在身体倒下后 |
| `{kind: "inbody"}` | `ConversionResult` |
| `{kind: "zip"}` | `RawServiceResult` 与无所损失 `Uint8Array` 内容 |
| `{kind: "presigned_url"}` | 每件文件的文物和结果数 |
| S3, Azure Blob, Google 云存储器, Google 驱动器, 或低级配置 | 结果计数 |

S3, Azure, GCS, Drive, 通用连接器, 回调, 并装入有效载荷可以携带 证书。 对请求机构和日志进行相应处理.

## 批次连接器

批量路由从远程连接器列出文档并写入 a 预签名或存储目标 :

```ts
const job = await client.submitBatch(
  {
    sources: [
      {
        kind: 's3',
        endpoint: 's3.us-east-1.amazonaws.com',
        access_key: process.env.S3_ACCESS_KEY!,
        secret_key: process.env.S3_SECRET_KEY!,
        bucket: 'incoming-documents',
        key_prefix: 'manuals/',
      },
    ],
    target: { kind: 'presigned_url' },
    callbacks: [
      {
        url: 'https://workflow.example.com/docling-progress',
        headers: { authorization: `Bearer ${process.env.CALLBACK_TOKEN}` },
      },
    ],
  },
  { outputFormats: ['json', 'md'] }
);

const result = await job.result();
```

批量来源支持HTTP,S3,Azure Blob,GCS,Google Drive,以及 前相兼容的通用连接器。 批次目标支持预先签名 艺术品,那些存储系统, 和通用连接器。 档案,身体,ZIP, 并且将目标放置在批量路线上被拒绝,匹配Python客户端.

## 转换和块

切入端点转换并切入一个服务任务 :

```ts
const result = await client.chunk('https://example.org/manual.pdf', {
  chunker: 'hybrid',
  convert_options: {
    do_ocr: true,
    table_mode: 'accurate',
  },
  chunking_options: {
    max_tokens: 384,
    tokenizer: 'sentence-transformers/all-MiniLM-L6-v2',
    merge_peers: true,
    include_raw_text: true,
    use_markdown_tables: true,
    use_markdown_images: true,
  },
  include_converted_doc: true,
});

console.log(result.chunks[0]?.text);
console.log(result.documents[0]?.content.json_content);
```

Python形状的超载也被支持:

```ts
const result = await client.chunk(
  'https://example.org/manual.pdf',
  'hierarchical',
  { do_ocr: true },
  { includeConvertedDoc: true }
);
```

使用 `submitChunk()`, (中文(简体) ), `submitChunkUrl()`, (中文(简体) ), `submitChunkFile()`,或 `submitChunkBinary()` 当需要工作手柄时。 JSON 块请求支持 多个源、回调、所有块选项 `include_converted_doc`多段块路由接受一个文件而不使用 支持回调.

虽然 `chunks` 是多克林将军的成员 `OutputFormat` 服务,服务 通过 `/v1/chunk/{hybrid|hierarchical}/{source|file}/async`设置 `to_formats: ["chunks"]` 在正常的转换.

## 风扇出

`submitAndRetrieveEach()` 接受 `Iterable` 财务报告和审定财务报表 `AsyncIterable` 输入, 保存 最多 `maxInFlight` 活动全任务周期和生产完成顺序 默认:

```ts
for await (const [item, outcome] of client.submitAndRetrieveEach(items, {
  maxInFlight: 8,
  ordered: false,
})) {
  if (outcome instanceof Error) {
    console.error(item.metadata, outcome);
  } else {
    console.log(item.metadata, outcome);
  }
}
```

选择 `target` 保留正确键入的预先签名或内置结果. 当超过64个工作在外出时 客户会用民意测验 而不是打开更多的WebSockets. `submitAndRetrieveMany()` 现为 被贬去的别名.

## 任务周期

`DoclingJob` 揭露:

-   `taskId`, (中文(简体) ), `submittedAt`, (中文(简体) ), `queuePosition`, (中文(简体) ), `done`,并全部缓存 `TaskStatusResponse` 结束 `status`· ;
-   `poll()`, (中文(简体) ), `watch()`, (中文(简体) ), `wait()`, (中文(简体) ), `getResult()`,以及 `result()`。 。 。 .

`client.job(taskId, status?, loader?)` 附属于现有工作。 网络安全套 监视是默认的,用查询参数认证,并且在节点中, (单位:千美元) `X-Api-Key`,执行服务 `next` 握手、重新连接运输 失败最多3次,可以回到长选票. 投票使用 `GET /v1/status/poll/{task_id}?wait=...`。 。 。 .

所有等待者接受 `AbortSignal`。结果查找区分一个未知的任务, a 未准备好的结果、过期的终端结果和权威任务 失败.

## 检讨和错误

默认 `FetchTransport` 匹配 Python 重试策略 :

-   HTTP 500和502重试每一种方法都有指数回放;
-   HTTP 429 和 503 仅重试有效 `Retry-After`· ;
-   运输故障重试仅用于GET、HEAD和选项;
-   (一) 不再对取消打电话者进行再审;
-   健康与版本通话使用零回覆.

所有服务故障都源于 `DoclingServiceError`。 。 。 . 专门错误涵盖HTTP响应,已用尽/无法使用服务, 使用限制、 响应- schema 错配、 任务执行、 任务超时、 任务 未找到、结果未就绪、结果已逾期、文物下载和 高级转换失败.

## 指定文物安全

高级转换可以实现JSON文物或资源捆绑. 下载者 :

-   从不向文物主机转发 Docling 服务信头;
-   仅允许 HTTP( S), 解析每个 DNS 地址, 并拒绝任何非全局 地址,除非另有明确配置;
-   重新验证每个方向, 并有5个方向默认值;
-   执行超时、压缩-下行、未压缩-捆绑和入行计数 限制;
-   验证 ZIP 路径, 需要完全一个顶级 Docling JSON 文件,以及 在嵌入数据 URI 之前验证引用的图像 MIME 签名 .

下载或重建失败成为失败 `ConversionResult`,哪个 让我们 `convertAll()` 继续。 取消电话仍然在宣传.

## 转换选项

`ConvertDocumentsOptions` 明确输入当前 Python/ Serve 字段 : 格式选择、管道、页面范围、OCR、PDF后端、表格提取、, 图像导出、代码/公式/图片/图表浓缩、VLM预设和自定义 配置、布局/表/分类预设、已贬值的遗留VLM和 图片描述选项、超时和中止行为.

选项浅析合并: 构造器默认值被复制, 按调值 替换顶级字段, `undefined` 默认值保持不变 `null` 清除可选默认值。 索引签名保留了前向兼容性 在本套软件包之前添加了管理服务选项 服务的 OpenAPI 文档仍然具有权威性.

## 粘贴文档类型

客户故意不插针 `@docling/docling-core`默认值 `DoclingDocument` 是版本中立的 JSON 边界。 申请 从他们安装的核心包中精确的策略可以参数化客户端:

```ts
import type { DoclingDocument } from '@docling/docling-core';
import { DoclingClient } from '@docling/docling-client';

const client = new DoclingClient<DoclingDocument>({ baseUrl, apiKey });
```

这使得服务客户的发布独立于文档-schema发布 在需要时保留完整的静态打字.

## 自定义运输

N8n等主机可以注入HTTP:

```ts
import { DoclingClient, type DoclingTransport } from '@docling/docling-client';

const transport: DoclingTransport = {
  async request<T>(request) {
    return platformHttpRequest(request) as Promise<T>;
  },
  async close() {
    await platformHttpClose();
  },
};

const client = new DoclingClient({
  baseUrl: 'https://managed-docling.example.com',
  transport,
});
```

海关运输是完整的HTTP政策边界:必须保存 二进制响应,精确200个行为,重试/错误映射,头部,超时, 和取消说明 `DoclingTransportRequest`。它不能合并 带有内置获取/重试选项。 WebSocket 监视和文物 下载仍可单独注入.

## 发展

```sh
npm install
npm run check
```

单元套房不需要现场服务。 为了验证终点,反应内容, 计划财产、所需地段、目标/连接器和电源相容性 反对运行中的服务 :

```sh
DOCLING_API_KEY=... \
  npm run contract:check -- https://managed-docling.example.com/openapi.json
```

见 [Python 客户端均等](https://npmcn.com/package/%40docling/docling-client/PYTHON_CLIENT_PARITY.md) 全体会议 特征比较.

## 常见问题

### @docling/docling-client 是什么？

用于 Docling Service 和用于 IBM Watsonx 的 Docling 脚本客户端 \.

### 如何安装 @docling/docling-client？

在项目目录运行 npm install @docling/docling-client，或使用 pnpm add / yarn add / bun add。

### @docling/docling-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @docling/docling-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @docling/docling-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @docling/docling-client 可以商用吗？

@docling/docling-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @docling/docling-client 的下载量有多少？

根据 npm 官方下载统计，@docling/docling-client 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,966 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @docling/docling-client 还在维护吗？

最新版本 2\.150\.0 发布于 2026/11/11（2 天前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/07/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。