Grok Collections APIの使い方｜社内PDFをアップロードしてRAG検索する方法

Grok Collections APIを使うと、社内マニュアル、仕様書、PDF、CSV、テキストファイルなどをコレクションへ登録し、Grokから検索して回答へ反映できます。一般のWeb検索では見つからない、自社固有の情報を扱うRAG構成に向いています。

実装で迷いやすいのは、コレクション管理と推論で使うAPIキーが異なること、ファイルのアップロードとコレクションへの追加が別操作であることです。検索だけを先に作るのではなく、文書の更新、削除、権限、引用元表示まで含めて設計する必要があります。

この記事では、JavaScriptからコレクションを作成し、PDFをアップロードして追加し、ハイブリッド検索とResponses APIのfile_searchで回答を作る流れを解説します。

情報確認日：2026年7月11日（日本時間）

結論：管理APIと推論APIを分け、回答には引用元を必ず残す

Grok Collections APIとは？

Collectionsは、複数のファイルをまとめて検索対象にする仕組みです。ファイルをアップロードすると、検索に使えるように解析・索引化されます。Grokは質問に関連する箇所を取得し、その情報を使って回答できます。

よくある用途は次のとおりです。

• 社内規程や運用マニュアルを検索するチャット
• 製品仕様書から回答するサポート画面
• APIドキュメントを参照する開発者向けアシスタント
• 障害対応手順や過去の報告書を検索する運用ツール
• 契約書や資料の中から関連箇所を探すレビュー補助

Grok Web Searchとの違い

Collectionsは「非公開情報を検索できる」ことが利点ですが、登録しただけで正しい回答が保証されるわけではありません。文書の分割、表や画像の読み取り、更新日、重複文書、質問の曖昧さによって検索結果は変わります。

必要な2種類のAPIキー

Management APIキー

コレクションの作成、文書の追加・削除など、管理操作に使います。推論用の通常キーとは権限を分けて保管します。

通常のxAI APIキー

ファイルのアップロード、文書検索、Grokによる回答生成に使います。

XAI_API_KEY=your_inference_api_key
XAI_MANAGEMENT_API_KEY=your_management_api_key

プロジェクトを準備する

mkdir grok-collections-sample
cd grok-collections-sample
npm init -y
npm install openai dotenv
npm pkg set type=module
mkdir documents

検索したいPDFをdocuments/manual.pdfとして配置します。実際のアプリでは、アップロード前にファイル形式、サイズ、ウイルス、個人情報を検査してください。

コレクションを作成する

create-collection.jsを作成します。

import "dotenv/config";

const managementKey = process.env.XAI_MANAGEMENT_API_KEY;

if (!managementKey) {
  throw new Error("XAI_MANAGEMENT_API_KEYが設定されていません");
}

const response = await fetch(
  "https://management-api.x.ai/v1/collections",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${managementKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      collection_name: "product-manuals",
    }),
  },
);

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `コレクション作成に失敗しました: ${response.status} ${JSON.stringify(body)}`,
  );
}

console.log(body);

実行します。

node create-collection.js

応答に含まれるコレクションIDを保存します。名前ではなくIDを環境変数やデータベースへ記録すると、同名コレクションがある場合も取り違えにくくなります。

XAI_COLLECTION_ID=collection_id_here

PDFをアップロードする

ファイル本体は通常のxAI APIへアップロードします。Node.js 20以降のBlobとFormDataを使う例です。

upload-file.jsを作成します。

import "dotenv/config";
import { readFile } from "node:fs/promises";
import { basename } from "node:path";

const apiKey = process.env.XAI_API_KEY;
const filePath = "./documents/manual.pdf";

if (!apiKey) {
  throw new Error("XAI_API_KEYが設定されていません");
}

const bytes = await readFile(filePath);
const form = new FormData();

form.append(
  "file",
  new Blob([bytes], { type: "application/pdf" }),
  basename(filePath),
);

const response = await fetch("https://api.x.ai/v1/files", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
  body: form,
});

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `ファイルアップロードに失敗しました: ${response.status} ${JSON.stringify(body)}`,
  );
}

console.log(body);

応答に含まれるファイルIDを保存します。

XAI_FILE_ID=file_id_here

ファイルをコレクションへ追加する

アップロードしただけでは、まだコレクションの検索対象になりません。Management APIでコレクションとファイルを関連付けます。

attach-document.jsを作成します。

import "dotenv/config";

const managementKey = process.env.XAI_MANAGEMENT_API_KEY;
const collectionId = process.env.XAI_COLLECTION_ID;
const fileId = process.env.XAI_FILE_ID;

if (!managementKey || !collectionId || !fileId) {
  throw new Error("管理キー、コレクションID、ファイルIDを確認してください");
}

const url =
  `https://management-api.x.ai/v1/collections/` +
  `${encodeURIComponent(collectionId)}/documents/` +
  `${encodeURIComponent(fileId)}`;

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${managementKey}`,
  },
});

const text = await response.text();

if (!response.ok) {
  throw new Error(
    `文書追加に失敗しました: ${response.status} ${text}`,
  );
}

console.log(text || "文書をコレクションへ追加しました");

文書の解析が完了するまで、検索へ反映されない場合があります。アップロード直後に結果が0件でも、失敗と決めつけず、文書状態を確認してください。

Documents Search APIで検索する

まずは回答生成を行わず、検索結果そのものを確認します。これにより、回答品質の問題が「検索」と「生成」のどちらにあるか切り分けられます。

search-documents.jsを作成します。

import "dotenv/config";

const apiKey = process.env.XAI_API_KEY;
const collectionId = process.env.XAI_COLLECTION_ID;

const response = await fetch("https://api.x.ai/v1/documents/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "パスワードを忘れた場合の復旧手順",
    source: {
      collection_ids: [collectionId],
    },
    retrieval_mode: "hybrid",
  }),
});

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `文書検索に失敗しました: ${response.status} ${JSON.stringify(body)}`,
  );
}

console.dir(body, { depth: null });

keyword検索

製品名、エラーコード、関数名、規程番号など、表記が一致しやすい検索に向きます。

semantic検索

利用者の言い換えや自然文から、意味が近い箇所を探す場合に向きます。

hybrid検索

キーワードと意味検索を組み合わせます。最初の基準として使い、実際の質問セットで比較します。

Responses APIのfile_searchで回答を作る

検索結果の確認後、Grokに回答を作らせます。OpenAI SDKのベースURLをxAI APIへ変更します。

import "dotenv/config";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
  timeout: 120_000,
});

const collectionId = process.env.XAI_COLLECTION_ID;

const response = await client.responses.create({
  model: "grok-4.5",
  input: `
登録された社内マニュアルだけを根拠として、
パスワードを忘れた利用者の復旧手順を説明してください。

手順が資料にない場合は推測せず、
担当部署への確認が必要だと回答してください。
`,
  tools: [
    {
      type: "file_search",
      vector_store_ids: [collectionId],
    },
  ],
});

console.log(response.output_text);
console.dir(response.output, { depth: null });

SDKやAPIの更新により、引用元が含まれる場所やフィールド名が変わる場合があります。実際のレスポンスをログで確認し、本文と出典を分けて保存してください。

引用元を画面へ表示する

RAG画面では、回答だけを表示すると利用者が正しさを確認できません。少なくとも次の情報を表示します。

• 参照した文書名
• 該当ページやセクション
• 短い引用または関連箇所へのリンク
• 文書の更新日
• 回答を生成した日時

文書の更新を設計する

ファイル名だけで同一文書を判定しない

文書ID、版、更新日、ハッシュ値を管理します。同名の古いPDFと新しいPDFが同時に残ると、矛盾した回答の原因になります。

公開前と公開後のコレクションを分ける

レビュー中の文書を本番検索へ混ぜないよう、ステージング用と本番用のコレクションを分離します。

削除を同期する

元のストレージから削除した文書が検索側に残らないよう、削除ジョブと監査ログを用意します。

検索品質を評価する方法

「それらしい回答が返った」だけでは評価できません。実際に利用者が聞く質問を20〜100件ほど用意し、検索と回答を分けて確認します。

Webアプリへ組み込む構成

管理者画面
  ├─ ファイル検査
  ├─ xAI Files APIへアップロード
  ├─ Management APIでCollectionへ追加
  ├─ 文書状態・版・更新日をDBへ保存
  └─ 古い文書を削除

利用者画面
  ├─ 認証・部署権限を確認
  ├─ 質問を制限・監査
  ├─ file_searchを実行
  ├─ 回答を生成
  └─ 引用元と原文リンクを表示

1つのコレクションに全社文書を入れ、プロンプトだけで閲覧制御しないでください。部署や顧客ごとに検索対象を分け、サーバー側で許可されたコレクションIDだけを選びます。

セキュリティと運用上の注意点

• 個人情報、契約情報、秘密情報のアップロード条件を確認する
• 管理キーと推論キーを分け、最小権限で保管する
• 文書内の指示を信頼しない。間接プロンプトインジェクションを想定する
• 検索結果に含まれるURLやコマンドを自動実行しない
• 回答、引用元、利用者、時刻を監査できるようにする
• 料金と検索回数に上限・アラートを設定する

あわせて読みたい記事

• Grokとは？できること・X連携・画像生成・API・設定方法を解説
• Grok X Search APIの使い方
• Grok Voice Agent APIの使い方
• AI APIキーを安全に管理する方法

よくある質問

まとめ

Grok Collections APIを使うと、自社文書を検索対象にしたRAGアプリを構築できます。実装は、コレクション作成、ファイルアップロード、文書追加、検索、回答生成の順で進めます。

本番運用では、回答生成よりも、文書の版管理、削除同期、部署権限、引用元表示、検索品質の評価が重要です。まず検索APIだけで正しい箇所を取得できるか確認し、その後にGrokの回答生成を重ねてください。

参考リンク

• xAI Docs – Collections
• xAI Docs – Collections API
• xAI Docs – Collections Search
• xAI REST API – Collections
• xAI API Pricing