文件与集合

文件

查看 Markdown

Grok 可以搜索和推理你附加到聊天消息中的文档。可以通过 URL 引用任何公开文件,也可以 上传上传私有文件并通过 ID 引用;无论采用哪种方式,系统都会自动启用 attachment_search 工具,并将请求转换为智能体工作流。

更多信息请参阅 Files API 参考

想了解集合?如果需要持久化文档存储和跨大量文档的语义搜索,请参阅 集合。Files 则用于将文档附加到聊天对话中,作为即时上下文。


Files 如何与聊天配合工作

在后台,将文件附加到聊天消息时,xAI API 会隐式地向请求添加 attachment_search 服务器端工具。这意味着:

  1. 自动智能体行为:聊天请求会变成智能体请求,由 Grok 自主搜索你的文档

  2. 智能文档分析:模型可以推理文档内容、提取相关信息并综合生成答案

  3. 多文档支持:可以附加多个文件,Grok 会跨所有文件进行搜索

通过这种无缝集成,只需附加文件并提问,智能体工作流便会自动处理文档搜索和检索的复杂工作。


将文件附加到聊天消息时,xAI API 会自动启用 attachment_search 服务器端工具。这会将请求转换为 智能体工作流,其中 Grok 会:

  1. 分析你的查询,了解你要查找的信息

  2. 搜索文档,智能地从所有附加文件中找到相关部分

  3. 提取并综合信息,必要时整合多个来源

  4. 提供全面答案,并结合文档中的上下文

智能体工作流

与其他智能体工具(Web Search、X Search、代码执行)一样,文档搜索会自主运行:

  • 多次搜索:模型可能使用不同查询多次搜索文档,以找到全面的信息

  • 推理:模型利用推理能力决定搜索内容以及如何解释结果

  • 流式状态可见性:在流式模式中,可以通过工具调用通知查看模型何时搜索文档

Files 的 token 用量

基于文件的聊天与其他智能体请求具有相似的 token 使用模式:

  • 提示 token:包括对话历史和内部处理。文档内容会得到高效处理

  • 推理 token:用于规划搜索和分析文档内容

  • 补全 token:最终答案文本

  • 缓存 token:重复的文档内容可受益于 prompt 缓存,提高效率

实际文档内容由服务器端工具处理,不会直接出现在消息历史中,从而优化 token 使用量。

定价

除标准 token 费用外,文档搜索还按每次工具调用计费。模型每搜索一次文档,就计为一次工具调用。完整定价详情请参阅 Tool 定价 表格。


开始使用

要在 Grok 中使用文件,需要:

  1. 获取文件的 公开 URL,或者了解如何通过 Files API

  2. 与文件聊天,将文件附加到聊天消息并针对文档提问


快速示例

以下是完整工作流的快速示例:

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.20grok-4.5grok-4.6grok-4.7

  • 支持的文件格式

    • 纯文本文件(.txt)

    • Markdown 文件(.md)

    • 代码文件(.py、.js、.java 等)

    • CSV 文件(.csv)

    • JSON 文件(.json)

    • PDF 文档(.pdf)

    • 以及许多其他基于文本的格式


下一步


最后更新:2026 年 9 月 21 日