mixedbread-search

Mixedbread Search

Stores API を使用して、管理されたナレッジベースを作成し、検索します。Stores は、100 以上の言語にわたってテキスト、画像、表、音声、動画を扱うマルチモーダル検索インデックスです。

ドキュメント：https://www.mixedbread.com/docs/stores/overview.md エージェントが読み取り可能なドキュメント：https://www.mixedbread.com/docs/llms.txt 最新のドキュメント検索：https://www.mixedbread.com/question?q=stores&section=docs

セットアップ

pip install mixedbread          # Python
npm install @mixedbread/sdk     # TypeScript

export MXBAI_API_KEY=your_api_key

クイックスタート

Python：

import os
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key=os.environ["MXBAI_API_KEY"])

store = mxbai.stores.create(name="my-docs", description="Product documentation")

mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("guide.pdf", "rb"),
    metadata={"category": "guides", "version": "2.0"},
)

results = mxbai.stores.search(
    query="How does authentication work?",
    store_identifiers=["my-docs"],
    top_k=5,
)
for chunk in results.data:
    print(f"{chunk.score:.3f} | {chunk.filename}: {chunk.text[:100]}")

TypeScript：

import { Mixedbread } from '@mixedbread/sdk';
import fs from 'fs';

const mxbai = new Mixedbread({
    apiKey: process.env.MXBAI_API_KEY!,
});

const store = await mxbai.stores.create({
    name: 'my-docs',
    description: 'Product documentation',
});

await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('guide.pdf'),
    body: { metadata: { category: 'guides', version: '2.0' } },
});

const results = await mxbai.stores.search({
    query: 'How does authentication work?',
    store_identifiers: ['my-docs'],
    top_k: 5,
});

判断ツリー

• どのような検索が必要ですか？
  • シンプルなキーワード／セマンティック検索 → top_k を指定して標準の search() を使用
  • 引用付きの自然言語回答 → question_answering() を使用（引用はデフォルトで有効です）
  • アダプティブなセマンティック検索、完全一致検索、メタデータ検索、ドキュメント単位の探索が役立つ複雑な複数段階の質問 → agentic を有効にして search() を使用
  • トークン／正規表現による完全一致（エラーコード、識別子、文字列そのもの） → POST /v1/stores/grep を使用。Grep とチャンク一覧を参照してください。
  • 社内ドキュメントとリアルタイムのウェブ検索を組み合わせる → store_identifiers に "mixedbread/web" を追加
• メタデータによるフィルタリングが必要ですか？
  • どのメタデータがあるか不明 → まず metadata_facets() を呼び出す
  • フィールドがわかっている → all／any／none の組み合わせで filters を構築する
• 関連性を高める必要がありますか？
  • はい → search_options で "rerank": true を設定します（デフォルトモデル mixedbread-ai/mxbai-rerank-v3-listwise を使用）。モデルの選択、再ランキングへのメタデータの追加、再ランキング後の結果数の上限設定を行うには、設定オブジェクト {"rerank": {"model": "...", "with_metadata": true, "top_k": 10}} を渡します。
• ファイルから OCR、要約、文字起こしを取得する必要がありますか？
  • はい → config: {"parsing_strategy": "high_quality"} を指定してファイルをアップロードします。Stores は OCR テキスト、要約、文字起こしを自動抽出するため、個別に解析する必要はありません。PDF、スライド、Word 文書、画像の場合、チャンクにはさらに generated_metadata.layout にページごとのレイアウト情報が含まれます。これには、各検出要素のバウンディングボックス（ページ画像のピクセル単位で [x1, y1, x2, y2]）、要素の種類、OCR テキストが読み取り順で格納されます。
  • いいえ／テキストのみのドキュメント → デフォルトの parsing_strategy（"fast"）で十分です。
• ユーザーのクエリ言語は、メタデータフィールド（タイトル、カテゴリ、作成者）と重なりますか？
  • はい → ストアの作成時に contextualization を有効にして、埋め込みにそのメタデータを含めます。コンテキスト化を参照してください。
  • いいえ → デフォルトのまま無効にしておきます。
• 既知のファイルについて、クエリではなく保存済みのチャンクそのものが必要ですか？
  • はい → return_chunks=True（またはインデックスのリスト）を指定して stores.files.retrieve() を呼び出します。ファイル単位でチャンクを取得を参照してください。
  • いいえ。関連性順のランキングが必要 → search() を使用します。
• ストアは一時的なもの（例：PR レビュー）ですか？
  • はい → 作成時に日数制限を指定して expires_after を設定します

ワークフロー

検索可能なナレッジベースの構築

ストアを作成し、ドキュメントをアップロードして検索します。ほとんどの場合、ファイルの処理完了を確認するためのポーリングは不要です。ベンチマークや再現率の評価など、ワークフローでバッチ全体の処理完了が必要な場合に限り、処理完了を待ちます。

Python：

store = mxbai.stores.create(
    name="product-docs",
    description="Product documentation",
    config={"contextualization": {"with_metadata": ["title", "category"]}},
)

mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("guide.pdf", "rb"),
    metadata={"title": "Setup Guide", "category": "guides"},
)
mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("faq.md", "rb"),
    metadata={"title": "FAQ", "category": "support"},
)

results = mxbai.stores.search(
    query="How do I reset my password?",
    store_identifiers=["product-docs"],
    top_k=5,
    search_options={"rerank": True},  # file metadata is returned by default
)
for chunk in results.data:
    print(f"{chunk.score:.3f} | {chunk.filename}: {chunk.text[:100]}")

# Optional: poll store.file_counts if you need deterministic full-batch coverage (benchmarks, migrations).

TypeScript：

const store = await mxbai.stores.create({
    name: 'product-docs',
    description: 'Product documentation',
    config: { contextualization: { with_metadata: ['title', 'category'] } },
});

await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('guide.pdf'),
    body: { metadata: { title: 'Setup Guide', category: 'guides' } },
});
await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('faq.md'),
    body: { metadata: { title: 'FAQ', category: 'support' } },
});

const results = await mxbai.stores.search({
    query: 'How do I reset my password?',
    store_identifiers: ['product-docs'],
    top_k: 5,
    search_options: { rerank: true },  // file metadata is returned by default
});

// Optional: poll store.file_counts if you need deterministic full-batch coverage (benchmarks, migrations).

フィルター駆動の検索

利用可能なメタデータを確認してから、目的に合わせたフィルターを構築します。

Python：

facets = mxbai.stores.metadata_facets(store_identifiers=["product-docs"])
for key, values in facets.facets.items():
    print(f"{key}: {values}")

results = mxbai.stores.search(
    query="deployment guide",
    store_identifiers=["product-docs"],
    top_k=10,
    filters={
        "all": [
            {"key": "category", "operator": "eq", "value": "guides"},
            {"key": "status", "operator": "not_eq", "value": "archived"},
        ]
    },
    search_options={"rerank": True},
)

TypeScript：

const facets = await mxbai.stores.metadataFacets({
    store_identifiers: ['product-docs'],
});
for (const [key, values] of Object.entries(facets.facets ?? {})) {
    console.log(`${key}: ${JSON.stringify(values)}`);
}

const results = await mxbai.stores.search({
    query: 'deployment guide',
    store_identifiers: ['product-docs'],
    top_k: 10,
    filters: {
        all: [
            { key: 'category', operator: 'eq', value: 'guides' },
            { key: 'status', operator: 'not_eq', value: 'archived' },
        ],
    },
    search_options: { rerank: true },
});

フィルター演算子：eq、not_eq、gt、gte、lt、lte、in、not_in、like、not_like、contains、starts_with、regex。all（AND）、any（OR）、none（NOT）を組み合わせて使用します。

ウェブ検索を組み合わせた検索

store_identifiers に "mixedbread/web" を含めると、ストア検索とリアルタイムのウェブ検索結果を組み合わせられます。これは予約済みのストア識別子で、セットアップは不要です。ウェブだけを検索することもできます。

Python：

results = mxbai.stores.search(
    query="latest best practices",
    store_identifiers=["my-docs", "mixedbread/web"],
)

TypeScript：

const results = await mxbai.stores.search({
    query: 'latest best practices',
    store_identifiers: ['my-docs', 'mixedbread/web'],
});

コンテキスト化

埋め込みの前に、選択したファイルのメタデータをチャンクテキストに追加します。これにより、title、category、author などのフィールドと重なるクエリの順位付けがより正確になります。作成時にストアの config.contextualization で設定し、それ以降にアップロードされたファイルにのみ適用されます。モード（false／true／{"with_metadata": [...]}）については、Stores ドキュメントを参照してください。このスキルの先頭にリンクされている llms.txt を取得し、Stores の設定ページへのリンクをたどってください。

ファイルごとのチャンク取得

すでに対象のファイルがわかっていて（プレビュー、エクスポート、取り込みのデバッグなど）、順位付けが不要な場合は、return_chunks=True（すべてのチャンク）または return_chunks=[indices]（特定の chunk_index の位置）を指定して stores.files.retrieve() を呼び出してください。正確なリクエスト／レスポンス形式については、API リファレンスの「Get Store File」エンドポイントを参照してください。llms.txt を取得してリンクをたどるか、ドキュメントを検索してください。

Grep とチャンク一覧表示（REST）

専用の SDK メソッドがまだない 2 つのエンドポイントです。HTTP（または SDK の汎用 post）で呼び出してください。

• POST /v1/stores/grep — 意味検索の代わりに、RE2 正規表現でチャンクを照合します。リテラルトークン、識別子、エラーコード、フレーズを含むチャンクを検索します。本文：pattern（正規表現、最大 1024 文字）、store_identifiers（ストアを正確に 1 つ指定）、targets（デフォルトは ["text", "generated"]。元のチャンクテキストと、取り込み時に生成された OCR テキスト、文字起こし、要約を対象にします）、case_sensitive（デフォルトは false）、top_k、filters。ページネーションはありません。該当結果を増やすには top_k を大きくしてください。レスポンスのチャンクは data に返されます。
• POST /v1/stores/list-chunks — 検索クエリなしで、メタデータ filters によってチャンクを一覧表示します。オプションでメタデータフィールドによる並べ替えも指定できます。降順にするには sort_by: "price" または ["price", false] を指定します（プレフィックスのないパスはファイルメタデータを対象とし、generated_metadata.* はチャンクメタデータを対象とします）。対象にできるストアは 1 つのみです。

質問応答

出典を引用した生成回答を取得します。回答には、出典リストを参照する <cite i="n"/> タグが含まれる場合があります。引用（qa_options.cite）とマルチモーダルコンテキスト（qa_options.multimodal）は、どちらもデフォルトで有効です。任意のトップレベルパラメーターとして、回答のスタイルや焦点を指定する instructions（最大 8,000 文字）と、回答をストリーミングする stream: true を指定できます。

Python：

result = mxbai.stores.question_answering(
    query="What are the rate limits?",
    store_identifiers=["my-docs"],
    top_k=10,
    search_options={"rerank": True},
)
print(result.answer)
for source in result.sources:
    print(f"  {source.filename} (score: {source.score:.3f})")

TypeScript：

const result = await mxbai.stores.questionAnswering({
    query: 'What are the rate limits?',
    store_identifiers: ['my-docs'],
    top_k: 10,
    search_options: { rerank: true },
});
console.log(result.answer);
for (const source of result.sources) {
    console.log(`  ${source.filename} (score: ${source.score.toFixed(3)})`);
}

エージェント型フォールバックを使った質問応答

QA で出典が返されなかった場合は、エージェント型検索で再試行して、より深く検索します。必ず question_answering() を再度呼び出してください。生成回答が得られなくなるため、search() を直接呼び出す方法にフォールバックしないでください。

Python：

result = mxbai.stores.question_answering(
    query="Compare the pricing tiers and their feature differences",
    store_identifiers=["my-docs"],
    top_k=10,
    search_options={"rerank": True},
)

if not result.sources:
    result = mxbai.stores.question_answering(
        query="Compare the pricing tiers and their feature differences",
        store_identifiers=["my-docs"],
        top_k=10,
        search_options={"agentic": True},
    )

print(result.answer)
for source in result.sources:
    print(f"  {source.filename} (score: {source.score:.3f})")

エージェント型検索

複数ステップの検索が必要な複雑な質問に使用します。agentic を有効にすると、Mixedbread のマネージド検索エージェントのハーネスに検索と順位付けが委任されます。最初に元のクエリとメタデータの調査を行い、その後、意味検索、完全一致／正規表現による照合、メタデータフィルタリング、コーパスの概要表示、チャンクまたはドキュメントの展開から、状況に応じて選択します。そして、最終的なエビデンスの順位付けを行います。検索を並列実行することもでき、呼び出し間でエビデンスを重複排除します。search() と question_answering() の両方で動作します。

内部で使われるツールの正確な順序は実装の詳細です。生成されるサブクエリの数を固定とみなしたり、トレースのツール名を前提にクライアントのロジックを構築したりしないでください。公開レスポンスは通常の順位付きチャンクリストのままです。question_answering() は、そのリストを使って出典付きの回答を生成します。

Python：

results = mxbai.stores.search(
    query="Compare the pricing tiers and their feature differences",
    store_identifiers=["product-docs"],
    top_k=10,
    search_options={
        "rerank": True,
        "agentic": {
            "instructions": (
                "Prioritize official pricing pages over blog posts. "
                "Surface tier names, monthly cost, and included feature lists."
            ),
        }
    },
)

TypeScript：

const results = await mxbai.stores.search({
    query: 'Compare the pricing tiers and their feature differences',
    store_identifiers: ['product-docs'],
    top_k: 10,
    search_options: {
        rerank: true,
        agentic: {
            instructions:
                'Prioritize official pricing pages over blog posts. ' +
                'Surface tier names, monthly cost, and included feature lists.',
        },
    },
});

エージェント機能のオプション

• agentic: true — デフォルト設定で有効にします。
• agentic: { ... } — 現在有効なリクエスト制御を使用します。
  • instructions（文字列、最大5000文字）— 追加の検索とランキングに関する指針です。重視するエンティティ、指標、期間、ソースの種類、権威性のルール、および無視する内容をエージェントに伝えます。トップレベルの query は引き続きユーザーの質問として扱われます。
  • strict_top_k（デフォルトは false）— 最終的なエビデンスの提出に、top_k 個のチャンクをちょうど含めることを必須にします。関連するチャンクが十分に含まれていない可能性がある、小規模または疎なストアでは無効のままにしてください。

管理対象のハーネスは、トップレベルの query、store_identifiers、top_k、filters、file_ids を使用します。filters と file_ids は厳密な範囲制約であり、エージェントが行うすべての検索に AND 条件で適用されます。一方、instructions は検索計画とランキングに関する柔軟な指針です。

リクエストスキーマでは、以前のエージェント機能との互換性のため、引き続き max_rounds、queries_per_round、media_content を受け付けますが、管理対象のハーネスは現在、これらのリクエストレベルの値を転送しません。調整には使用しないでください。管理対象エージェントでは、取得した画像コンテンツは現在無効になっており、リクエストレベルの score_threshold も転送されません。

agentic が有効な場合、管理対象エージェントが独自にクエリを計画するため、search_options.rewrite_query は不要です。エージェントによる検索と併せて rerank を有効にできます。この場合、エージェントが最終的なエビデンスのランキングを行う前に、セマンティック検索ツールが返した結果を再ランク付けします。

エージェントの instructions を適切に記述する

• 質問を言い換えるよりも、「Xを優先する」「Yを無視する」「Zを権威ある情報として扱う」といった指示表現を使用します。
• 探索とランキングの基準を明確にするため、具体的なエンティティ、フィールド、指標、期間、ドキュメントの種類を指定します。
• 適用可能な範囲制約には、トップレベルの filters または file_ids を使用します。メタデータフィルターで制約を表現できる場合は、「team=growth のみを検索する」といった指示に頼らないでください。
• 質問自体は query に記述し、ランキングや計画に関する指針は instructions に記述します。

レスポンス形式

検索結果（search() の戻り値）：

response.data  # list of chunks
chunk.text       # str — the matched text
chunk.score      # float — relevance score (0–1)
chunk.filename   # str — source file name
chunk.file_id    # str — source file ID
chunk.store_id   # str — store the chunk belongs to
chunk.metadata   # dict — attached file metadata (returned by default; disable with return_metadata=False)
chunk.type       # str — chunk type (e.g. "text", "image_url")
chunk.image_url  # dict | None — image payload for image chunks
chunk.ocr_text   # str | None — OCR text for image-heavy chunks
chunk.summary    # str | None — auto-generated summary for image chunks (high_quality mode)
chunk.transcription # str | None — transcription for audio/video chunks (high_quality mode)
chunk.generated_metadata # dict | None — ingestion-derived metadata (page counts, dimensions, headings, ...)

high_quality モードでは、PDF、スライド、Word、画像のチャンクにも、generated_metadata.layout の OCR レイアウトが表示されます。これには、ページ画像の width／height と、読み上げ順の elements が含まれます。各要素には、ページ画像のピクセル座標で表した bbox（[x1, y1, x2, y2]）、type（例：table、figure、text）、および要素の OCR text が含まれます。これを使ってエビデンスの領域を強調表示したり、回答をページ上の位置に対応付けたりできます。

QA の結果（question_answering() の戻り値）：

result.answer    # str — generated answer, may contain <cite i="n"/> tags
result.sources   # list of source objects
source.filename  # str
source.score     # float
source.file_id   # str
source.text      # str — the source chunk text
source.image_url # dict | None — image payload with url/format for image chunks

ストアの管理

stores = mxbai.stores.list(limit=20)
for store in stores.data:
    print(store.name)

store = mxbai.stores.retrieve(store_identifier="my-docs")
print(store.file_counts)  # {"completed": 5, "in_progress": 2, "failed": 0}

mxbai.stores.delete(store_identifier="my-docs")

files = mxbai.stores.files.list(store_identifier="my-docs", limit=20)
for file in files.data:
    print(file.filename, file.status)

ルール

重要

• ストア名には、小文字のアルファベット、数字、ハイフン、ピリオドのみを使用してください。 無効な名前を指定すると、作成に失敗します。スペース、アンダースコア、大文字は使用できません。
• フィールドレベルのコンテキスト化には、ドキュメントに記載されている {"with_metadata": [...]} 形式を使用してください。 その他のドキュメント記載モードは、true（すべてのメタデータ）と false（メタデータなし）です。ネストされたフィールドにはドット記法を使用できます。

HIGH

• 完全性が重要でない限り、取り込みの完了を待たないでください。 ストアはファイルを非同期で処理し、処理が完了したファイルから検索可能になります。ほとんどの場合、特に対話型のワークフローでは、ポーリングせずにアップロードしてすぐ検索してください。ベンチマーク、移行、同期の検証など、ワークフローでバッチ全体の網羅性が必要な場合に限り、ファイルのステータスまたは file_counts をポーリングしてください。
• フィルターを構築する前に metadata_facets() を使ってください。 メタデータのキーを推測せず、確認してください。フィルターキーの誤字は、結果が何も返されない原因になります。
• 本番環境での検索では rerank を有効にしてください。 再ランキングにより、関連性が大幅に向上します。レイテンシ重視のプロトタイプでのみ省略してください。
• 自動コンテンツ抽出を有効にするには、parsing_strategy: "high_quality" を使ってください。 アップロード時のファイルごとの設定で指定すると、high quality モードでは画像から OCR テキストと要約を、音声や動画から文字起こしを抽出します。これらのフィールドは LLM のコンテキストとして直接使用できます。また、PDF、スライド、Word、画像のチャンクでは、OCR テキストと並んで各要素のバウンディングボックスを含む generated_metadata.layout も生成されます。デフォルトの "fast" 戦略では、こうした追加の抽出を行わずにコンテンツをインデックス化します。
• 単純な検索には標準検索を使ってください。 エージェント型検索では、複数回の検索によってレイテンシが増加します。複雑な複数段階の質問でのみ使用してください。

MEDIUM

• 一時的なストアには expires_after を設定してください。 PR レビュー用、デモ用、テスト用のストアには、自動的に期限切れになるよう設定し、使われていないインデックスが蓄積しないようにしてください。
• クエリごとではなく、ナレッジドメインごとにストアを1つ作成してください。 ストアは再利用を前提とした永続的なインデックスです。作成は一度だけにして、繰り返し検索してください。
• 標準検索で関連性の低いノイズを除外するには、score_threshold を使ってください。 search_options: {"score_threshold": 0.3} を設定すると、サーバー側で最小関連度を下回るチャンクを除外できるため、クライアント側で chunk.score を使った後処理は不要です。現在、エージェント型検索では転送されません。
• 有効なエージェント型検索の制御項目のみ使ってください。 top_k を調整し、filters／file_ids で範囲を厳密に限定し、agentic.instructions で検索の方向性を指定してください。リクエストレベルの max_rounds、queries_per_round、media_content は互換性のためのフィールドであり、現在、管理対象のハーネスには転送されません。
• 検索の方向性を指定するには query ではなく agentic.instructions を使ってください。 query はユーザーの自然言語による質問のままにしてください。「Xを優先する」「Yを無視する」といった指示、ソースタイプの優先設定、ランキングのヒントは、search_options.agentic.instructions に記述してください（最大5000文字）。
• 画像クエリでサポートされるのは、プレーンなセマンティック検索のみです。 画像クエリと rerank、rewrite_query、agentic を組み合わせると、検証エラーが発生します。

トラブルシューティング

症状	原因	対処方法
検索結果が返されない	新しくアップロードしたファイルがまだ処理中、またはストア名／クエリが間違っている	少なくとも1つのファイルの処理が完了してから再試行してください。完全性が重要な実行では、結果を評価する前に、対象のファイルが completed になっていることを確認してください。
検索結果が返されない	スコアのしきい値が高すぎる	search_options.score_threshold（またはクライアント側のカットオフ）を下げるか、削除してください。
検索結果が返されない	store_identifiers が間違っている	ストア名または ID が完全に一致していることを確認してください。
メタデータフィルターで何も返されない	キー名または値が間違っている	metadata_facets() を使って、実際のキーと値を確認してください。
エージェント型検索が遅い	管理対象の複数ステップの探索で、モデル呼び出しと検索呼び出しが追加される	クエリが単純な場合は標準検索を使い、最終的に必要なチャンクが少ない場合は top_k を減らし、agentic.instructions をより具体的にしてください。互換性のみを目的とする max_rounds や queries_per_round を調整しようとしないでください。
API キーのエラー	キーが無効、または設定されていない	MXBAI_API_KEY が設定されていることを確認してください。キーは https://platform.mixedbread.com/platform?next=api-keys で取得してください。