Moonshot API 是月之暗面推出的 OpenAI 兼容接口，Kimi 系列模型中的 moonshot-v1-128k 支持 128K 上下文。长文档问答、合同分析、财报解读等场景下，原始 PDF 或 Word 文件不能直接塞进模型，必须通过文件接口上传、抽取文本，再在 Chat Completions 中引用。本文将拆解这套文件处理链路的每个环节，并给出可执行的 Python 与 cURL 示例。
一、理解文件接口与超长上下文的配合方式
文件接口的核心是把二进制文档转成模型可读的文本。上传后返回的 file_id 不是文件地址，而是一个引用句柄。Chat Completions 在构造 messages 时，可以把 file_id 作为 content 的一个子项传入，平台会读取已抽取的文本并注入上下文。这个过程对调用方透明，不需要在客户端处理 PDF 解析、Word 转换或 OCR。
超长上下文的价值在于一次可以加载大量内容。128K 上下文大约可以容纳数万字到十几万字的中文或英文 tokens，具体取决于分词。文件上传后无需自己切分文本，但如果抽取内容超过模型窗口，仍需要先分块或截断。因此在使用前要确认模型名称，涉及长文档时建议选择 moonshot-v1-128k，而不是 8K 或 32K 模型。
文件接口不是 RAG，而是直接把文件文本放入上下文。优点是语义完整、调用简单，缺点是 token 消耗较高。对超大文件，仍建议结合分片、摘要或外部向量库做筛选，避免无意义的全文注入。
二、上传文件与获取 file_id
调用上传接口需要 multipart/form-data 格式，字段 file 是二进制文件本体，purpose 固定为 file-extract。使用 cURL 时用 -F 参数。上传成功后返回文件元信息，其中 id 用于后续引用。
curl https://api.moonshot.cn/v1/files \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -F "file=@/data/report.pdf" \ -F "purpose=file-extract"
Python requests 更适合自动化。构造 files 和 data 字典，发送 POST 请求即可完成上传。
import requests
url = "https://api.moonshot.cn/v1/files"
headers = {
"Authorization": "Bearer " + MOONSHOT_API_KEY
}
files = {
"file": open("/data/report.pdf", "rb")
}
data = {
"purpose": "file-extract"
}
resp = requests.post(url, headers=headers, files=files, data=data)
print(resp.status_code)
print(resp.json())
上传成功后，返回的 JSON 包含文件元信息。其中 id 是后续对话中必须使用的引用值，bytes 可以用于校验文件大小，filename 保留原始文件名。
{
"id": "file-abc123",
"object": "file",
"bytes": 1048576,
"created_at": 1710000000,
"filename": "report.pdf",
"purpose": "file-extract"
}
三、在对话中引用文件并提问
上传完成后，关键是把 file_id 放入 Chat Completions 请求。messages 数组中的 user content 可以是字符串，也可以是一个数组。数组形式支持同时传入多个文件和文本。每个文件子项使用 type 为 file，并携带 file_id 和可选的 filename。
import requests
url = "https://api.moonshot.cn/v1/chat/completions"
headers = {
"Authorization": "Bearer " + MOONSHOT_API_KEY,
"Content-Type": "application/json"
}
payload = {
"model": "moonshot-v1-128k",
"messages": [
{"role": "system", "content": "你是一个严谨的分析助手。"},
{"role": "user", "content": [
{"type": "file", "file_id": "file-abc123", "filename": "report.pdf"},
{"type": "text", "text": "请总结这份报告的核心结论，并列出三个风险点。"}
]}
],
"temperature": 0.3
}
resp = requests.post(url, headers=headers, json=payload)
print(resp.json())
多文件场景下，可以在 content 数组中放置多个 file 子项，也可以在后续对话中继续引用同一 file_id。由于每个文件都会进入上下文，需要注意 token 总量。如果响应提示 context length exceeded，可以删除部分文件，或对文本进行摘要后再追问。
与普通文本相比，文件引用会先经过平台抽取，因此无需自己在客户端处理 PDF 解析。但要注意，文件抽取结果会占用上下文窗口，同一文件每次请求都会重新计入 token，因此频繁调用时缓存 file_id 并不能减少 token 计算，只能减少上传时间。
四、文件管理接口与抽取结果查看
文件上传后可以通过 GET /files 查看全部文件，GET /files/{file_id} 查看单个元信息，GET /files/{file_id}/content 获取平台抽取的纯文本。这些接口帮助判断文件是否成功解析，以及内容长度是否超出窗口。
curl https://api.moonshot.cn/v1/files/file-abc123/content \ -H "Authorization: Bearer $MOONSHOT_API_KEY"
抽取结果示例如下，内容为纯文本，可能包含换行和空白。拿到这段文本后，可以在客户端先做长度检查，再决定是否直接进入对话或进行二次切割。
{
"content": "这是从 report.pdf 中抽取出的文本内容，可能包含换行和空白。"
}
删除接口 DELETE /files/{file_id} 用于清理不再使用的文件。虽然平台可能不会长期保留文件内容，但在敏感场景下建议在处理完立即删除。Python 调用方式如下。
import requests
headers = {
"Authorization": "Bearer " + MOONSHOT_API_KEY
}
resp = requests.delete(
"https://api.moonshot.cn/v1/files/file-abc123",
headers=headers
)
print(resp.status_code)
文件内容为抽取后的纯文本，不保留表格样式、图片位置等排版信息。对于扫描件或复杂表格，抽取效果会下降，此时应先在客户端做预处理或 OCR 校验，确认文本质量后再上传。
五、异常排查与工程化建议
常见错误包括：401 Authorization header 缺失或密钥错误；400 参数错误或 purpose 不正确；413 文件超过大小限制；422 文件已损坏或格式不支持。响应体一般包含 error.message，先看 message 再排查。下面是一个典型错误响应。
{
"error": {
"message": "The file could not be parsed.",
"type": "invalid_request_error",
"code": "file_parse_error"
}
}
生产环境建议将上传和对话分离，文件上传可异步化。对同一文件避免重复上传，使用数据库保存 file_id 与内容哈希。在每次对话前估算 token，超长时先分块摘要。如果需批量处理多个文件，可使用队列控制并发，避免触发限流。
总结来说，文件处理接口是进入 Kimi 超长上下文能力的第一道门，掌握上传、引用、管理和删除四个步骤，就能将 PDF、Word 等资料直接变成对话材料。下一步可以尝试构造多文件交叉分析的 Prompt，或通过 system 消息约束输出格式，进一步提升文档问答质量。
Moonshot APIKimi超长上下文文件处理修改时间：2026-08-24 18:14:18