Similarity Search Api Sdk

相似度搜索 API

基于预计算向量的无状态相似度搜索——融合 NMI（归一化互信息）和余弦相似度，并针对每个请求计算经过熵校准的混合权重。无需向量数据库，无需维护索引，也无需运行基础设施。

既可作为普通 HTTP API 使用，也可作为 MCP 服务（5 个工具）供 AI Agent 使用。

---

重要：此 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 付款 （参见下方“定价”）。这些路由已于 2026-08-25 移除 X-API-Key 验证；Stripe 按量计费也明确排除了它们，因此目前在这 3 个路由上提供密钥没有任何作用。已弃用且不计价的 /similarity/calibrate-alpha（没有 /v1 后缀）仍需要 X-API-Key，并且始终返回 501。

/health 无需身份验证。

定价

有两种付款方式，适用于相同的端点：

• x402（按调用付费，使用 Base 上的 USDC）——目前运行于 Base Sepolia 测试网，每次调用 $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 能捕捉余弦相似度的几何夹角所无法体现的统计依赖关系。

---

限制

• 语料库大小：每个请求最多 500,000 个条目
• 向量维度：2-4,096
• batch-score 配对数：每个请求最多 10,000 对