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

# PDF 文件

> 将 PDF 作为知识输入，完成总结、问答、字段提取、表格整理和结构化输出。

PDF 文件能力适合处理合同、论文、产品手册、财务报表、说明书和导出的业务文档。你可以把 PDF 内容作为上下文交给模型，再让模型总结、问答或提取字段。

## 处理方式

<Columns cols={2}>
  <Card title="短文档" icon="file">
    直接抽取文本后放入请求上下文，适合页数少、结构清晰的文件。
  </Card>

  <Card title="长文档" icon="files">
    按章节、页码或内容块拆分，便于在对话中定位和引用内容。
  </Card>
</Columns>

## 建议流程

<Steps>
  <Step title="抽取文本与页码">
    保留标题、页码、表格说明等引用信息，方便模型给出可追溯答案。
  </Step>

  <Step title="拆分文档块">
    长 PDF 按主题或页码拆分，避免一次性传入无关上下文。
  </Step>

  <Step title="选择输出格式">
    摘要用自然语言，字段提取用 JSON，复杂表格可要求 Markdown 表格。
  </Step>
</Steps>

<Warning>
  上传合同、财务、人事或客户资料前，请确认数据合规要求，并使用独立 API 密钥限制额度和模型范围。
</Warning>

## API 调用示例

接口调用时，常见做法是在你的服务端先抽取 PDF 文本，再把相关正文放入 `messages.content`。下面示例会读取 `contract.pdf`，让模型总结文档并提取关键字段。

将 PDF 文件放在项目根目录（即保存 `.py` 或 `.mjs` 代码文件、并从该目录运行命令的文件夹）中。代码里的 `PDF_PATH = "contract.pdf"` 就是要读取的文件名：你的文件叫 `invoice.pdf` 时，直接改成 `PDF_PATH = "invoice.pdf"`。文件名、扩展名和大小写必须与实际文件一致；文件不在项目根目录时，填写它的完整本地路径。无需单独上传 PDF，代码会读取该文件并把抽取出的文本随请求发送。

`PdfReader` 不是 Python 自带函数，它来自 `pypdf` 包；Node.js 示例里的 `PDFParse` 来自 `pdf-parse` 包。Python 与 Node.js 使用不同的包管理器：Python 请在项目文件夹终端执行下面的命令；Node.js 则在 `npm` 与 `pnpm` 中任选一种。

<CodeGroup>
  ```bash macOS / Linux theme={null}
  python3 -m pip install openai pypdf
  ```

  ```powershell Windows theme={null}
  py -m pip install openai pypdf
  ```
</CodeGroup>

<CodeGroup>
  ```bash npm theme={null}
  npm install openai pdf-parse
  ```

  ```bash pnpm theme={null}
  pnpm add openai pdf-parse
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  # PdfReader 来自 pypdf，用来打开 PDF 并读取每一页文本。
  from pypdf import PdfReader

  client = OpenAI(
      api_key="你的密钥",
      base_url="https://moxus.cloud/v1",
  )

  # 将 contract.pdf 放在项目根目录；替换为你的实际文件名。
  PDF_PATH = "contract.pdf"
  reader = PdfReader(PDF_PATH)

  # page.extract_text() 会抽取单页文字；如果某页没有可识别文本，就用空字符串兜底。
  pdf_text = "\n\n".join(page.extract_text() or "" for page in reader.pages)

  response = client.chat.completions.create(
      model="gpt-5.4-mini",
      messages=[
          {
              "role": "user",
              "content": f"请总结下面这个 PDF 文档，并提取合同主体、金额、日期和风险点：\n\nPDF file: {PDF_PATH}\n\n{pdf_text}",
          }
      ],
  )

  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";
  import { readFile } from "node:fs/promises";

  // PDFParse 来自 pdf-parse，用来把 PDF Buffer 解析成文本。
  import { PDFParse } from "pdf-parse";

  const client = new OpenAI({
    apiKey: "你的密钥",
    baseURL: "https://moxus.cloud/v1",
  });

  // 将 contract.pdf 放在项目根目录；替换为你的实际文件名。
  const PDF_PATH = "contract.pdf";
  // readFile 读取本地 PDF 文件；getText() 返回的 text 是抽取出的文本。
  const parser = new PDFParse({ data: await readFile(PDF_PATH) });
  const { text: pdfText } = await parser.getText();
  await parser.destroy();

  const response = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [
      {
        role: "user",
        content: `请总结下面这个 PDF 文档，并提取合同主体、金额、日期和风险点：\n\nPDF file: ${PDF_PATH}\n\n${pdfText}`,
      },
    ],
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

<Note>
  Python 示例需要先安装 `openai` 和 `pypdf`。Windows 中若 `py` 不可用，改用 `python -m pip install openai pypdf`；Node.js 示例需要使用 `npm` 或 `pnpm` 安装 `openai` 和 `pdf-parse`。如果 PDF 是扫描件，请先使用 OCR 提取文字。
</Note>

## 后续阅读

* [结构化输出](/zh/guide/structured-output)