ナレッジ検索(β版)

基本情報

この API は、miibo の RAG（Retrieval-Augmented Generation）システム用のベクトルデータベースにアクセスするためのインターフェースを提供します。

ベースURL

https://api-mebo.dev/knowledge/search

認証

APIリクエストには、HTTPヘッダーに有効なAPIキーが必要です。
miiboのAPI設定画面でAPIキーを取得してください。(ナレッジデータストア用のAPIキーを利用します。)

X-API-Key: YOUR_API_KEY

エンドポイント

発話の検索

指定されたベクトルに最も類似したベクトルを検索します。

• URL: /search

• メソッド: POST

  • リクエストボディ:

    JSON

    {
      "agent_id": "string",
      "utterance": "検索する発話",
      "metadata_filter": {
        "key1": "value1"
      }
    }
    

    パラメータ:

    パラメータ名	値	required	補足
    agent_id	String	✅	ナレッジデータストアが紐づくエージェントのID。
    utterance	String	✅
    url	String
    metadata_filter	String配列		CustomFieldと組み合わせてフィルタリングができます。
    limit	Int		取得する件数 (最大10000)
    use_lexical_search_only	Boolean		セマンティック検索ではなく、字句検索のみを行います。特定のキーワードにマッチするデータを取得したいときなどに有効です。(default: False) 未指定の場合、follow\_agent\_settings が true ならエージェント側の設定に従います。
    include_all_text	Boolean		レスポンス結果にチャンクだけでなく「全文」を含めるかどうか\ (default: False)
    search_query_model	String		※今後、公開予定\ (default: gpt-4o) gpt-4o-mini指定可能です
    history	String		検索クエリ生成に使う会話履歴。speaker1: ... / speaker2: ... 形式で指定します。指定すると通常チャットと同じ履歴ベースのクエリ生成に切り替わります。未指定時は utterance 単体からクエリを生成します。
    user_state	Object		検索クエリ生成プロンプト内の @{state:...} を解決するためのキーバリューペア。
    follow_agent_settings	Boolean		true を指定すると、検索クエリ生成モデル・字句/ミックス検索・スコア閾値をエージェント側の設定に従わせます。通常チャットと同じ設定源になるため、チャット同等の検索挙動を実現できます。エージェント側の検索クエリ生成モデルが未設定の場合は、通常チャットと同様にクエリ生成を行わず発話をそのまま検索に使います。ES からの取得件数も通常チャットと同じ 30 件を既定にします（limit が 30 より大きい場合は limit 件、fetch_limit を指定した場合はその件数。いずれも最大 200）。(default: false)
    use_mix_search	Boolean		ミックス検索（ベクトル検索結果と字句検索結果を交互配置）を行うかどうか。follow_agent_settings より優先されます。注意: Elasticsearch への検索が2回になるためレイテンシが増加します。
    score_threshold	Number		スコアの足切り閾値。この値未満のスコアを持つ検索結果は除外されます。follow_agent_settings より優先されます。
    fetch_limit	Integer		Elasticsearch から取得する件数。score_threshold や metadata_filter で絞られた後の返却件数が limit を下回る場合に、これより大きい値を指定して多めに取得してから絞り込む用途に使います。未指定時は limit と同じ件数を取得します。ES へ実際に投げる取得件数は最大 200（ベクトル検索の kNN top-K の上限）で、これを超える値は limit 経由で指定した場合も含め 200 に丸められます。

• レスポンス:

  JSON

  [
      {
        "label": "string",
        "score": float,
        "text": "string",
        "url": "string",
        "all_text": "string"
      }
  ]
  

  • 成功時 (200 OK)
  • エラー時 (400 Bad Request)
    JSON

    {
      "error": "Invalid search parameters"
    }

サンプル

下記が本APIの利用サンプルです。

curl -X POST "https://api-mebo.dev/knowledge/search" \
  -H "X-API-Key: <ナレッジデータストア用のAPI>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<ナレッジデータストアが紐づくエージェントのID>",
    "utterance": "<検索したい文字列>",
    "limit": 10
  }'

エラーハンドリング

全てのエンドポイントは、以下の共通エラーレスポンスを返す可能性があります：

• 400 Bad Request: リクエストの内容に不備がある場合
• 401 Unauthorized: APIキーが無効または不足している場合
• 429 Too Many Requests: レート制限を超えた場合
• 500 Internal Server Error: サーバー側のエラーが発生した場合