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

# 文档理解

> 通过 OpenAI 兼容的 /v1/chat/completions 调用 Gemini 文档理解能力。

Gemini OpenAI 兼容文档理解适合已经使用 OpenAI `chat/completions` 的客户，在同一个 `messages[].content` 数组中传入文本指令和文件内容。当前推荐写法是 `type: "file"` 搭配 `file.file_data` 的 data URL，适合 PDF、TXT、DOCX 等小到中等大小文件的联调和结构化抽取。

<Warning>
  在 OpenAI 兼容格式里，不要只把 PDF URL 当普通文本发给模型，否则模型可能只能看到 URL 字符串。大文件或远程文件可以评估 Gemini 原生 `fileData.fileUri`，但前提是 URL 必须是上游可直接读取、响应 MIME 正确的文件直链；不确定时请使用本页的 `file_data` data URL。
</Warning>

## 接口地址

```http theme={null}
POST https://{your-domain}/v1/chat/completions
```

OpenAI SDK 的 `base_url`：

```text theme={null}
https://{your-domain}/v1
```

示例模型：

```text theme={null}
gemini-3.5-flash
```

## 鉴权

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求结构

| 字段                         | 类型      | 必填   | 说明                                             |
| -------------------------- | ------- | ---- | ---------------------------------------------- |
| `model`                    | string  | 是    | 支持文档理解的 Gemini 模型名称。                           |
| `messages[].content`       | array   | 是    | 多模态内容数组，包含 `text` 和 `file`。                    |
| `content[].type`           | string  | 是    | 文本传 `text`，文件传 `file`。                         |
| `content[].text`           | string  | 文本必填 | 文档处理指令，例如摘要、抽取、问答、分类。                          |
| `content[].file.filename`  | string  | 文件必填 | 文件名，建议带真实扩展名。                                  |
| `content[].file.file_data` | string  | 文件必填 | data URL，例如 `data:application/pdf;base64,...`。 |
| `max_tokens`               | integer | 否    | 最大输出 token 数。                                  |
| `temperature`              | number  | 否    | 抽取任务建议低温度。                                     |
| `response_format`          | object  | 否    | 需要强结构化 JSON 时可传。                               |

常见 data URL 前缀：

| 文件类型     | data URL 前缀                                                                            |
| -------- | -------------------------------------------------------------------------------------- |
| PDF      | `data:application/pdf;base64,`                                                         |
| TXT      | `data:text/plain;base64,`                                                              |
| Markdown | `data:text/markdown;base64,`                                                           |
| DOCX     | `data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,` |

## 非流式文档理解

### curl

```bash theme={null}
curl --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请阅读这份 PDF，用中文输出：1. 核心摘要；2. 三条要点；3. 需要人工复核的字段。"
          },
          {
            "type": "file",
            "file": {
              "filename": "sample.pdf",
              "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
            }
          }
        ]
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.2,
    "stream": false
  }'
```

### 请求体

```json theme={null}
{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请阅读这份 PDF，用中文输出：1. 核心摘要；2. 三条要点；3. 需要人工复核的字段。"
        },
        {
          "type": "file",
          "file": {
            "filename": "sample.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
          }
        }
      ]
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.2,
  "stream": false
}
```

### 响应示例

```json theme={null}
{
  "id": "chatcmpl-doc-abc123",
  "object": "chat.completion",
  "created": 1784700000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. 核心摘要：这份 PDF 内容较短，主要用于验证文件读取和文档解析流程。\n\n2. 三条要点：\n- 文档结构简单，正文较少。\n- 可作为接口联调样例。\n- 不包含复杂表格、签章或多页长文本。\n\n3. 需要人工复核的字段：如果换成真实业务文件，合同金额、日期、签署方、身份证号、发票号码等字段建议人工复核。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 640,
    "completion_tokens": 158,
    "total_tokens": 798
  }
}
```

## 结构化 JSON 抽取

当客户需要固定字段，可以传 `response_format`。下面示例要求模型只返回 JSON。

```json theme={null}
{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是文档信息抽取助手。只返回 JSON，不要返回 Markdown。字段缺失时使用 null。"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "从文件中提取 title、date、parties、amount、summary。"
        },
        {
          "type": "file",
          "file": {
            "filename": "contract.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
          }
        }
      ]
    }
  ],
  "response_format": {
    "type": "json_object"
  },
  "max_tokens": 1200,
  "temperature": 0.1
}
```

响应示例：

```json theme={null}
{
  "id": "chatcmpl-doc-json-abc123",
  "object": "chat.completion",
  "created": 1784700000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"title\":\"样例合同\",\"date\":\"2026-07-22\",\"parties\":[\"甲方示例公司\",\"乙方示例公司\"],\"amount\":null,\"summary\":\"文档用于演示合同字段抽取。\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 780,
    "completion_tokens": 72,
    "total_tokens": 852
  }
}
```

## 流式文档理解

文档理解也可以尝试 `stream: true`。如果渠道不支持文件流式，建议改用非流式或 Gemini 原生流式。

```bash theme={null}
curl -N --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请流式总结这份 PDF，先输出摘要，再输出要点列表。"
          },
          {
            "type": "file",
            "file": {
              "filename": "sample.pdf",
              "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
            }
          }
        ]
      }
    ],
    "max_tokens": 1024,
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'
```

响应为 SSE：

```text theme={null}
data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"摘要：这份文档内容较短，主要用于验证文件读取流程。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"\n要点：\n- 文档结构简单。\n- 可用于接口联调。\n- 真实业务仍需人工复核关键字段。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":640,"completion_tokens":76,"total_tokens":716}}

data: [DONE]
```

## Python SDK 示例

```python theme={null}
import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://{your-domain}/v1",
)

pdf_bytes = Path("sample.pdf").read_bytes()
file_data = "data:application/pdf;base64," + base64.b64encode(pdf_bytes).decode("utf-8")

completion = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请总结这份 PDF，并列出三条要点。"},
                {
                    "type": "file",
                    "file": {
                        "filename": "sample.pdf",
                        "file_data": file_data,
                    },
                },
            ],
        }
    ],
    max_tokens=1024,
    temperature=0.2,
)

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

## JavaScript SDK 示例

```javascript theme={null}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://{your-domain}/v1",
});

const pdfBase64 = fs.readFileSync("sample.pdf").toString("base64");

const completion = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "请总结这份 PDF，并列出三条要点。" },
        {
          type: "file",
          file: {
            filename: "sample.pdf",
            file_data: `data:application/pdf;base64,${pdfBase64}`,
          },
        },
      ],
    },
  ],
  max_tokens: 1024,
  temperature: 0.2,
});

console.log(completion.choices[0].message.content);
```

## 选择 OpenAI 兼容还是 Gemini 原生

| 场景                 | 建议                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------- |
| 客户已有 OpenAI SDK 封装 | 使用 OpenAI 兼容格式。                                                                         |
| 小文件、低频联调、快速迁移      | 使用 `type: "file"` + `file_data`。                                                        |
| 大文件、远程文件 URL、长文档   | 若能提供上游可读且 `Content-Type` 正确的稳定直链，可评估 Gemini 原生 `fileData.fileUri`；否则拆分文件或继续使用 data URL。 |
| 需要视频理解             | 使用 Gemini 原生视频理解，不建议 OpenAI 兼容视频写法。                                                     |
| 需要完全贴近 Gemini 官方参数 | 使用 Gemini 原生格式。                                                                         |

## 常见问题

| 场景          | 表现                | 处理方式                                                                  |
| ----------- | ----------------- | --------------------------------------------------------------------- |
| 直接传 PDF URL | 模型只复述 URL 或说无法访问  | 改用 `type: "file"` + `file_data`；若使用 Gemini 原生 URL 方式，必须先确认 URL 是文件直链。 |
| 请求体过大       | 413、超时或上游拒绝       | 拆分文档，或转存为上游可读且响应 MIME 正确的稳定文件直链后再使用原生格式。                              |
| 文件无法解析      | MIME 与文件内容不一致     | 使用真实 MIME 类型，并保留正确文件扩展名。                                              |
| 抽取 JSON 不稳定 | 返回 Markdown 或自然语言 | 使用 system 指令、`response_format`，并在业务侧做 JSON 校验。                        |
| 关键字段不可信     | 模型可能误读扫描件或表格      | 对金额、日期、身份信息、合同主体等字段保留人工复核。                                            |