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

# 长上下文（Long Context）

> 了解算秩长上下文模型如何处理长文档、代码片段、历史对话和 RAG 结果，并合理管理 token 预算和输出长度。

长上下文（Long Context）用于让模型在单次请求中接收更多上下文信息，例如长文档、代码库片段、历史对话、检索结果或多份材料。相比只输入简短 prompt，长上下文可以减少预先裁剪信息的成本，让模型基于更完整的材料完成阅读、分析和生成任务。

长上下文不等于长期记忆。模型只能在当前请求的上下文窗口内参考输入内容；请求之外的历史、文件或外部知识，仍需要由应用重新传入、检索后注入，或通过其他产品能力管理。

## 使用场景

* **长文档问答**：把合同、报告、论文或产品文档作为上下文，让模型回答与材料相关的问题。
* **文档总结与对比**：对长篇材料进行摘要、提纲整理、差异对比或风险点提取。
* **代码库理解**：输入多个文件、调用链或错误日志，让模型分析实现逻辑、定位问题或提出修改建议。
* **多轮对话延续**：在会话中保留必要历史，让模型理解前文约束和用户偏好。
* **RAG 结果整合**：把检索到的多个片段放入上下文，让模型基于证据生成答案。

## 支持的模型

不同模型支持的上下文窗口不同。使用前请在 [模型广场](https://console.siflow.cn/model-inference/models) 查看模型详情，确认模型的上下文长度、最大输出长度、价格和能力支持情况。

<Note>
  上下文窗口、最大输出长度和价格属于易变信息。正式接入时，请以模型广场展示的模型详情为准，不要只依赖文档中的示例模型。
</Note>

## 工作机制

一次模型请求中的上下文通常由以下内容组成：

* `system` 消息中的角色、规则和输出要求。
* `user` 消息中的当前问题、任务说明和待处理材料。
* 历史 `assistant` / `user` 消息。
* 应用注入的文档片段、检索结果、代码、日志或结构化数据。
* 模型本次需要生成的输出预算。

上下文窗口可以理解为模型当前请求可使用的工作空间。输入内容和输出内容都会占用 token 预算，因此在处理长材料时，需要为模型最终回答预留足够的输出空间。

多轮 `messages` 中的历史消息也会作为当前请求上下文的一部分传入。保留更多历史可以帮助模型理解前文，但也会占用上下文窗口；如果历史过长，建议只保留必要轮次，或将历史整理成摘要后再传入。

典型流程如下：

1. 选择支持足够上下文长度的模型。
2. 清理和组织要传入的材料，去除无关内容。
3. 在 prompt 中明确任务、材料边界和输出格式。
4. 设置合理的 `max_completion_tokens`，为最终回答预留输出空间。
5. 发送请求并根据结果判断是否需要拆分材料、补充检索或调整 prompt。

## 与 RAG 和 Prompt Cache 的关系

Long Context、RAG 和 Prompt Cache 解决的问题不同：

| 能力           | 主要作用                | 适合场景                    |
| ------------ | ------------------- | ----------------------- |
| Long Context | 在单次请求中放入更多上下文       | 材料规模可控，且需要模型整体理解上下文     |
| RAG          | 先检索相关片段，再把片段放入请求    | 知识库较大、问题范围不固定、需要降低无关上下文 |
| Prompt Cache | 复用重复上下文，降低重复处理成本或延迟 | 多次请求共享相同长前缀或固定系统提示      |

<Note>
  本页只说明 Long Context 的使用方式。Prompt Cache / Context Cache 是否可用、如何开启以及如何计费，请以对应能力文档或 API 指南为准。
</Note>

## 关键参数

* `messages`：承载系统提示、用户问题、历史对话和长材料。长材料应有清晰边界，避免模型混淆材料正文和用户指令。
* `model`：选择具体模型。不同模型的上下文窗口和最大输出长度不同，请以模型广场为准。
* `max_completion_tokens`：控制模型本次生成的最大输出长度。处理长输入时，不要把全部上下文预算都留给输入，应为输出预留空间。如果输出达到该上限，响应可能以 `finish_reason: "length"` 结束，内容可能被截断。
* `stream`：长回复场景可以设置为 `True`，让客户端边接收边展示输出，降低等待体感。

<Note>
  对于会生成 reasoning 内容的模型，推理过程也可能占用输出预算。如果 `max_completion_tokens` 设置过小，可能出现最终回答被截断，甚至 `content` 为空的情况。
</Note>

完整请求参数和返回字段请以 API 指南为准。能力文档只说明 Long Context 的基本使用方式和应用侧处理责任。

## 使用建议

* **先判断是否真的需要长上下文**：如果问题只依赖少量片段，优先传入最相关内容，而不是整份材料。
* **保留材料结构**：为不同文档、章节、代码文件或检索结果添加标题和分隔符，帮助模型识别信息边界。
* **减少无关内容**：上下文越长，成本和延迟通常越高；无关信息过多也可能干扰模型判断。
* **明确任务和依据范围**：说明模型应基于哪些材料回答，是否可以使用通用知识，以及输出应采用什么格式。
* **为输出预留空间**：长输入场景仍需要设置合理的 `max_completion_tokens`，避免回答被截断。
* **为 reasoning 和最终回答预留预算**：如果模型会生成 reasoning 内容，请同时考虑推理过程和最终回答对输出预算的占用。
* **长回复结合 Streaming**：如果预期输出较长，可以启用 `stream=True`，让用户更早看到生成结果。
* **设置更长的客户端超时**：超长输入会增加处理时间，不同模型的响应延迟可能差异明显。生产环境中应结合模型、输入长度和网络情况设置超时策略。
* **大规模知识库优先结合检索**：如果材料远超单个请求可承载范围，或问题只需要局部信息，建议先用 Embedding / RAG 找到相关片段，再交给模型生成答案。

## 限制说明

* 不同模型的上下文窗口、最大输出长度和计费方式不同，请以模型广场为准。
* 长上下文会增加输入 token 数，通常也会增加成本和响应延迟。
* 上下文更长不一定意味着结果更好。过多无关、重复或冲突的信息可能降低回答质量。
* 如果输入和预期输出超过模型限制，请减少输入内容、拆分任务，或选择上下文窗口更大的模型。
* 模型不会自动记住前一次请求中没有再次传入的内容。需要延续上下文时，应用应显式传入必要历史或摘要。
* 单次请求成功处理较长输入，不代表该模型或平台的最大上下文上限。最大上下文长度、最大输出长度和超限行为请以模型详情和实际 API 返回为准。
* 长上下文请求可能返回 `usage.prompt_tokens`、`usage.completion_tokens` 等用量信息；部分模型还可能返回 reasoning tokens 或 cached tokens 等明细字段。具体字段和计费口径请以 API 指南和用量统计页面为准。
* 与 Structured Output、Function Calling、Streaming、RAG 或缓存能力组合使用时，请分别确认相关能力的支持范围和参数要求。

## 调用示例

示例使用环境变量读取 API Key，避免将密钥写入代码。

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

这段代码完成以下处理：

1. 将长材料放入 `user` 消息。
2. 使用明确的分隔符标记材料边界。
3. 要求模型只基于给定材料回答。
4. 设置 `max_completion_tokens`，为输出预留预算。

示例中的模型仅用于展示调用方式。实际接入时，请在模型广场选择支持目标上下文长度的模型，并确认该模型的价格、最大输出长度和能力限制。

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://api.siflow.cn/model-api",
)

document = """
在这里放入需要分析的长文档、代码片段、会议记录或检索结果。
实际使用时，可以由应用从文件、数据库或检索系统中读取并拼接。
"""

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro",
    messages=[
        {
            "role": "system",
            "content": "你是一名严谨的文档分析助手。请只基于用户提供的材料回答。",
        },
        {
            "role": "user",
            "content": f"""
请阅读以下材料，并输出：
1. 三条核心结论；
2. 需要进一步确认的问题；
3. 可执行的下一步建议。

<document>
{document}
</document>
""",
        },
    ],
    max_completion_tokens=1024,
)

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