文件与集合
文件
Grok 可以搜索和推理你附加到聊天消息中的文档。可以通过 URL 引用任何公开文件,也可以 上传上传私有文件并通过 ID 引用;无论采用哪种方式,系统都会自动启用 attachment_search 工具,并将请求转换为智能体工作流。
更多信息请参阅 Files API 参考。
想了解集合?如果需要持久化文档存储和跨大量文档的语义搜索,请参阅 集合。Files 则用于将文档附加到聊天对话中,作为即时上下文。
Files 如何与聊天配合工作
在后台,将文件附加到聊天消息时,xAI API 会隐式地向请求添加 attachment_search 服务器端工具。这意味着:
自动智能体行为:聊天请求会变成智能体请求,由 Grok 自主搜索你的文档
智能文档分析:模型可以推理文档内容、提取相关信息并综合生成答案
多文档支持:可以附加多个文件,Grok 会跨所有文件进行搜索
通过这种无缝集成,只需附加文件并提问,智能体工作流便会自动处理文档搜索和检索的复杂工作。
理解文档搜索
将文件附加到聊天消息时,xAI API 会自动启用 attachment_search 服务器端工具。这会将请求转换为 智能体工作流,其中 Grok 会:
分析你的查询,了解你要查找的信息
搜索文档,智能地从所有附加文件中找到相关部分
提取并综合信息,必要时整合多个来源
提供全面答案,并结合文档中的上下文
智能体工作流
与其他智能体工具(Web Search、X Search、代码执行)一样,文档搜索会自主运行:
多次搜索:模型可能使用不同查询多次搜索文档,以找到全面的信息
推理:模型利用推理能力决定搜索内容以及如何解释结果
流式状态可见性:在流式模式中,可以通过工具调用通知查看模型何时搜索文档
Files 的 token 用量
基于文件的聊天与其他智能体请求具有相似的 token 使用模式:
提示 token:包括对话历史和内部处理。文档内容会得到高效处理
推理 token:用于规划搜索和分析文档内容
补全 token:最终答案文本
缓存 token:重复的文档内容可受益于 prompt 缓存,提高效率
实际文档内容由服务器端工具处理,不会直接出现在消息历史中,从而优化 token 使用量。
定价
除标准 token 费用外,文档搜索还按每次工具调用计费。模型每搜索一次文档,就计为一次工具调用。完整定价详情请参阅 Tool 定价 表格。
开始使用
要在 Grok 中使用文件,需要:
快速示例
以下是完整工作流的快速示例:
import os
from xai_sdk import Client
from xai_sdk.chat import user, file
client = Client(api_key=os.getenv("XAI_API_KEY"))
# 1a. Reference a public file by URL
file_url = "https://example-files.online-convert.com/document/txt/example.txt"
# 1b. Or upload a file and reference by ID
uploaded_file = client.files.upload(
b"Employee: Alice Johnson\\nDepartment: Engineering",
filename="employee.txt",
)
# 2. Chat with files
chat = client.chat.create(model="grok-4.7")
chat.append(user(
"Summarize both documents",
file(url=file_url),
file(uploaded_file.id),
))
# 3. Get the answer
response = chat.sample()
print(response.content)
# 4. Clean up uploaded file
client.files.delete(uploaded_file.id)主要功能
多文件支持
将 多个文档 附加到单个查询,Grok 会在所有文档中搜索相关信息。
多轮对话
文件上下文会在多个 对话轮次 之间保留,因此无需重新附加文件即可继续追问。
代码执行集成
将文件与 代码执行工具 结合,可对上传的数据执行高级数据分析、统计计算和转换。模型可以编写并执行直接处理文件的 Python 代码。
限制
文件大小:每个文件最大 512 MB
不支持批处理请求:带文档搜索的文件附件属于智能体请求,不支持批处理模式(
n > 1)仅限智能体模型:需要支持智能体工具调用的模型(例如
grok-4.20、grok-4.5、grok-4.6、grok-4.7)支持的文件格式:
纯文本文件(.txt)
Markdown 文件(.md)
代码文件(.py、.js、.java 等)
CSV 文件(.csv)
JSON 文件(.json)
PDF 文档(.pdf)
以及许多其他基于文本的格式
下一步
最后更新:2026 年 9 月 21 日