文件与集合

文件

Grok 可以搜索并推理您附加到聊天消息中的文档。您可以通过 URL 引用任何公共文件，或上传私有文件并通过 ID 引用它们；无论哪种方式，系统都会自动激活 attachment_search 工具，并将您的请求转换为代理工作流。

您可以在 Files API 参考中查看更多信息。

正在寻找集合？ 如果您需要跨多个文档的持久文档存储和语义搜索，请参阅集合。文件则不同——它们用于将文档附加到聊天对话中以提供即时上下文。

文件如何与聊天协作

在幕后，当您将文件附加到聊天消息时，xAI API 会隐式地将 attachment_search 服务器端工具添加到您的请求中。这意味着：

自动代理行为：您的聊天请求会变成代理请求，Grok 会自主搜索您的文档
智能文档分析：模型可以推理文档内容，提取相关信息并综合答案
多文档支持：您可以附加多个文件，Grok 将在所有这些文件中进行搜索

这种无缝集成允许您只需附加文件并提问——文档搜索和检索的复杂性由代理工作流自动处理。

理解文档搜索

当您将文件附加到聊天消息时，xAI API 会自动激活 attachment_search 服务器端工具。这会将您的请求转换为代理工作流，其中 Grok：

分析您的查询 以了解您正在寻找的信息
智能搜索文档，在所有附加文件中找到相关部分
根据需要从多个来源提取和综合信息
提供包含文档上下文的全面答案

代理工作流

与其他代理工具（网络搜索、X 搜索、代码执行）一样，文档搜索也是自主运行的：

多次搜索：模型可能会使用不同的查询多次搜索文档，以找到全面的信息
推理：模型使用其推理能力来决定搜索什么以及如何解释结果
流式可见性：在流式模式下，您可以通过工具调用通知看到模型何时在搜索您的文档

使用文件的 Token 消耗

基于文件的聊天遵循与其他代理请求类似的 token 模式：

提示 token：包括对话历史和内部处理。文档内容被高效处理
推理 token：用于规划搜索和分析文档内容
完成 token：最终的答案文本
缓存 token：重复的文档内容受益于提示缓存以提高效率

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

定价

文档搜索按工具调用计费，此外还有标准的 token 费用。每次模型搜索您的文档时，都算作一次工具调用。有关完整的定价详情，请参阅工具定价表格。

入门指南

要将文件与 Grok 一起使用，您需要：

获取文件的公共 URL 或学习如何通过 Files API 上传、列出、检索和删除文件。
与文件聊天 - 将文件附加到聊天消息并询问有关您文档的问题

快速示例

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

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.5")
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)

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.5",
    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}\` },
});

主要功能

多文件支持

将多个文档附加到单个查询中，Grok 将在所有这些文件中搜索以查找相关信息。

多轮对话

文件上下文在对话轮次之间保持，允许您提出后续问题而无需重新附加文件。

代码执行集成

将文件与代码执行工具结合使用，对您上传的数据执行高级数据分析、统计计算和转换。模型可以编写并执行直接处理您文件的 Python 代码。

限制

文件大小：每个文件最大 48 MB
不支持批量请求：带有文档搜索的文件附件是代理请求，不支持批量模式（n > 1）
仅限代理模型：需要支持代理工具调用的模型（例如 grok-4.20、grok-4.5）
支持的文件格式：
- 纯文本文件（.txt）
- Markdown 文件（.md）
- 代码文件（.py、.js、.java 等）
- CSV 文件（.csv）
- JSON 文件（.json）
- PDF 文档（.pdf）
- 以及许多其他基于文本的格式

文件与集合 ​

文件 ​

文件如何与聊天协作 ​

理解文档搜索 ​

代理工作流 ​

使用文件的 Token 消耗 ​

定价 ​

入门指南 ​

快速示例 ​

主要功能 ​

多文件支持 ​

多轮对话 ​

代码执行集成 ​

限制 ​

后续步骤 ​