调试客户端

@docling/docling-client 是 TypeScript 的正式客户端 导航服务 管理 实施相同API的道克服务,包括IBM主持道克.

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

安装

npm install @docling/docling-client

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

配置

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。 。 。 .

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 在不中断不相关的工作的情况下, 值 :

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

提交任务并选择目标

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

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);

具体目标成果静态输入:

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

批次连接器

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

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客户端.

转换和块

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

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形状的超载也被支持:

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 活动全任务周期和生产完成顺序 默认:

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 边界。 申请 从他们安装的核心包中精确的策略可以参数化客户端:

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

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

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

自定义运输

N8n等主机可以注入HTTP:

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 监视和文物 下载仍可单独注入.

发展

npm install
npm run check

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

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

见 Python 客户端均等 全体会议 特征比较.