从写代码,到创作下一幕

探索 字节跳动 - 火山方舟 的 AI 编程与视频创作活动。

火山方舟 Agent Plan 与 Coding Plan 活动,价格 ¥9.9 起

Agent Plan & Coding Plan

一站体验多款热门模型,为 AI 编程与智能体开发提供更多选择。新用户可联系(微信: goo_lvyouyou)免费体验 9.9 agent plan。

查看套餐优惠
Seedance 2.5 视频创作活动:30 秒视频、多模态参考、局部编辑

Seedance 2.5

让创意,跃然成片。探索 30 秒视频、多模态参考与局部编辑,把脑海中的画面变成下一支作品。

探索视频创作

文件与集合

文件

查看 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. 与文件聊天,将文件附加到聊天消息并针对文档提问


快速示例

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

JavaScript

// 1a. Reference a public file by URL
const fileUrl = "https://docs.x.ai/assets/api-examples/documents/sales-report.txt";

// 1b. Or upload a file and reference by ID
const formData = new FormData();
formData.append("file", new Blob(["Employee: Alice Johnson\\nDepartment: Engineering"], { type: "text/plain" }), "employee.txt");
formData.append("purpose", "assistants");

const uploadRes = await fetch("https://api.x.ai/v1/files", {
  method: "POST",
  headers: { Authorization: \`Bearer \${process.env.XAI_API_KEY}\` },
  body: formData,
});
const uploadedFile = await uploadRes.json();

// 2. Chat with files
const chatRes = await fetch("https://api.x.ai/v1/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: \`Bearer \${process.env.XAI_API_KEY}\`,
  },
  body: JSON.stringify({
    model: "grok-4.7",
    input: [
      {
        role: "user",
        content: [
          { type: "input_text", text: "Summarize both documents" },
          { type: "input_file", file_url: fileUrl },
          { type: "input_file", file_id: uploadedFile.id },
        ],
      },
    ],
  }),
});

// 3. Get the answer
const chatData = await chatRes.json();
const lastMessage = chatData.output[chatData.output.length - 1];
const answer = lastMessage?.content?.find((c) => c.type === "output_text")?.text;
console.log(answer);

// 4. Clean up
await fetch(\`https://api.x.ai/v1/files/\${uploadedFile.id}\`, {
  method: "DELETE",
  headers: { Authorization: \`Bearer \${process.env.XAI_API_KEY}\` },
});

Python

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 年 10 月 10 日