Similarity Search Api Sdk

類似度検索 API

事前計算済みベクトルに対するステートレスな類似度検索です。NMI（正規化相互情報量）とコサイン類似度を融合し、リクエストごとにエントロピーで調整したブレンド重みを計算します。ベクトルデータベースも、メンテナンスが必要なインデックスも、実行するインフラストラクチャも不要です。

プレーンな HTTP API と、AI エージェント向けの MCP サーバー（5 つのツール）の両方で利用できます。

---

重要：この API が扱うのはベクトルであり、生テキストではありません

この API はテキストを埋め込みベクトルに変換しません。query と corpus の項目には、事前計算済みの数値ベクトル（独自の埋め込みモデルで生成したものなど）を指定します。テキストを先にベクトルへ変換する必要がある場合は、上流でその処理を実行し、生成したベクトルをここに渡してください。

---

ベース URL

https://similarity-search-api-production.up.railway.app

認証

3 つのビジネスエンドポイント（/similarity/search、/similarity/calibrate-alpha/v1、 /similarity/batch-score）は API キー不要です。有効な x402 決済のみが必要です （「料金」を参照）。これらのルートでは X-API-Key による制限は 2026-08-25 に廃止されました。また、Stripe の従量課金でも明示的に対象外のため、 現在、これら 3 つのルートにキーを渡しても何も起こりません。非推奨で料金設定のない /similarity/calibrate-alpha（/v1 のサフィックスなし）は引き続き X-API-Key が必要で、 いずれにしても常に 501 を返します。

/health に認証は不要です。

料金

同じエンドポイントで、2 つの支払い方法を利用できます。

• x402（呼び出しごとの支払い、Base 上の USDC） — 現在は Base Sepolia テストネットで、1 回の呼び出しにつき $0.01 です。x402 決済フロー以外にアカウントや API キーは必要ありません。支払いなしのリクエストには 402 Payment Required が返され、決済の詳細は payment-required レスポンスヘッダーに含まれます。
• Stripe（従量課金） — API キーを発行され、アカウントに Stripe の顧客アカウントが登録されている呼び出し元向けです。

---

エンドポイント

POST /similarity/search

複合スコアを使用して、クエリベクトルに対するコーパスの項目を順位付けします。

{
  "query": { "id": "q1", "vector": [0.12, -0.4, 0.91, "..."] },
  "corpus": [
    { "id": "doc1", "vector": [0.10, -0.35, 0.88, "..."] },
    { "id": "doc2", "vector": [0.55, 0.02, -0.14, "..."] }
  ],
  "top_k": 10,
  "nmi_bins": 10,
  "alpha_override": null
}

query と corpus のすべてのベクトルは、同じ次元数（2～4096 次元）である必要があります。top_k は最大 1000 です。alpha_override（任意）を指定すると、コーパスのエントロピーから調整する代わりに、コサイン類似度と NMI のブレンド重みを固定できます。

レスポンス：

{
  "results": [
    { "id": "doc1", "composite_score": 0.91, "cosine_similarity": 0.89, "nmi_score": 0.94, "rank": 1 }
  ],
  "calibrated_alpha": 0.73,
  "corpus_entropy": 3.85,
  "query_id": "q1",
  "corpus_size": 2,
  "latency_ms": 43,
  "request_fingerprint": "..."
}

POST /similarity/calibrate-alpha/v1

検索全体を実行せずに、コーパスに対するエントロピー調整済みの alpha を計算します。検索リクエストを送信する前に、調整の挙動を確認・デバッグするのに便利です。

POST /similarity/batch-score

固定の alpha を使用して、最大 10,000 組の (vector_a, vector_b) をスコアリングします。コーパスやエントロピーの計算は不要です。

{
  "pairs": [[[0.1, 0.2], [0.15, 0.19]]],
  "alpha": 0.5,
  "nmi_bins": 10
}

GET /health

稼働状態の確認用エンドポイントです。認証は不要です。Stripe と x402 のどちらでも課金対象外です。

注：POST /similarity/calibrate-alpha（/v1 なし）は後方互換性のために残されている非推奨のエイリアスです。/similarity/calibrate-alpha/v1 を使用してください。

---

MCP ツール

MCP 対応クライアント（Claude、Cursor など）を、次のストリーミング可能な HTTP エンドポイントに接続してください。 https://similarity-search-api-production.up.railway.app/mcp

5 つのツールを提供します：rank_items_by_nmi_cosine_fusion、estimate_corpus_entropy_profile、score_pair_nmi_cosine、find_outlier_vectors_by_nmi_deficit、calibrate_alpha_from_query_entropy。

---

スコアリング方法

composite_score = alpha * cosine(query, doc) + (1 - alpha) * NMI_normalized(query, doc)

alpha は、送信されたコーパスのシャノンエントロピーに基づいてリクエストごとに調整されます（alpha_override を指定した場合を除く）。エントロピーが高い（分散した）コーパスではコサイン類似度の比重が高くなり、エントロピーが低い（密で狭い）コーパスでは NMI の比重が高くなります。NMI は、コサイン類似度では捉えられない統計的依存関係を捉えます。

---

制限

• コーパスサイズ：1 リクエストにつき最大 500,000 項目
• ベクトルの次元数：2～4,096
• batch-score のペア数：1 リクエストにつき最大 10,000