Grok 文件与集合检索

「我把文档传上去，模型就能一直记住吧？」——不能。Files 与 Collections 是两套东西：前者是把文档附加到一次对话，后者是持久存储 + 跨文档语义搜索。用 Files 做知识库，用户换个会话就问不到了；用 Collections 做一次性附件，又白白多了一层管理成本。

这一节先把两者分清，再给一个决策函数。

一、问题不是「能不能传文件」，而是「文件活多久」

官方对两者的定位说得很清楚：

• Files：把文档附加到聊天消息，支持公开 URL 或上传后按 ID 引用。系统会自动激活 attachment_search 服务端工具，把请求变成 agentic 工作流。文档内容由服务端工具处理，不直接进消息历史。
• Collections：持久化文档存储，带嵌入索引，支持跨多个文档、多个集合的语义搜索。创建集合时可自动生成 embeddings，一个文件可属于多个集合。

一句话区分：Files 解决「这次对话要看这份文档」，Collections 解决「以后都能搜到这批文档」。

二、最小可运行示例：先判断该用哪一个

下面的脚本不联网、不需要真实密钥。它根据文档数量、是否需要持久、是否需要元数据过滤、单文件大小给出选择。

"""Files vs Collections 决策（mock）：先看大小上限，再看使用形态。"""

def choose_store(doc_count: int, need_persistent: bool,
                 need_filter: bool, file_mb: int) -> str:
    if file_mb > 512:
        return "超过 Files 512MB 上限：必须先拆分"
    if file_mb > 100:
        return "Collections 单文件上限 100MB：改用 Files，或拆分后再入集合"
    if need_persistent and doc_count > 5:
        return "Collections（持久存储 + 跨文档语义搜索）"
    if need_filter:
        return "Collections（支持元数据过滤）"
    return "Files（附加到单次对话即可）"

def offline_check() -> None:
    cases = [
        ("少量临时附件", 3, False, False, 10),
        ("长期知识库", 50, True, False, 20),
        ("按作者过滤", 10, False, True, 5),
        ("超大单文件", 10, True, False, 200),
    ]
    for label, n, p, f, mb in cases:
        print(f"{label}：{choose_store(n, p, f, mb)}")

if __name__ == "__main__":
    offline_check()

真正落地时，doc_count 与 file_mb 换成你实际的文档画像。注意两个上限不一样：Files 单文件 512MB，Collections 单文件 100MB——这条差异经常被忽略，结果是「准备了半天的集合，上传时才发现超限」。

三、Files 与 Collections 的关键差异

三件要强调的事：

• Collections 需要账户有 credits。官方写明上传文件并加入集合前必须有余额；这不是「能不能用」的问题，是「能不能开始」的问题。
• 元数据是 Collections 的独有能力。required、unique、inject_into_chunk 这些选项，让「按作者过滤」「把标题注入切片」成为可能；Files 没有这一层。
• Files 不支持 batch。官方写明附件检索是 agentic 请求，不支持 n > 1；批量场景要自己串行或换方案。

四、预期输出与异常分支

运行决策函数，预期输出：

少量临时附件：Files（附加到单次对话即可）
长期知识库：Collections（持久存储 + 跨文档语义搜索）
按作者过滤：Collections（支持元数据过滤）
超大单文件：Collections 单文件上限 100MB：改用 Files，或拆分后再入集合

换成真实上传时，若出现异常，按下面顺序定位：

最后一行尤其重要：元数据不是上传后补的，而是在建集合时定义；事后想加，往往要重建索引。

五、判据卡

这张卡的重点是先分清生命周期。五条里有三条在说：文件活多久，决定了用哪套。

六、来源与核验

• 官方 Files：https://docs.x.ai/developers/files（核验日期 2026-11-04）。公开 URL / 上传按 ID 引用、自动激活 attachment_search、单文件 512MB、不支持 batch、支持的模型与格式，均以该页为准。
• 官方 Collections：https://docs.x.ai/developers/files/collections（核验日期 2026-11-04）。持久存储与语义搜索、嵌入索引、元数据字段、单文件 100MB、需 credits、不使用用户数据训练的口径来自该页。
• 官方 Collections Search：https://docs.x.ai/developers/tools/collections-search（核验日期 2026-11-04）。collections_search（xAI SDK）与 file_search（OpenAI Responses API）的命名差异、max_num_results 参数以该页为准。

七、动手试

1. 给你的文档集算一次「该用哪个」：列出文档数、单文件大小、是否需要长期检索，再对照本节的决策函数。
2. 设计一个 Collections 的元数据方案：至少三个字段，说明哪个该 required、哪个该 unique、哪个该 inject_into_chunk。
3. 写一条「Files 与 Collections 混用」的流程：本次对话附加临时文件，同时检索长期集合。说明两次请求的参数差异。