xtraceai/xtrace-sdkxtrace sdkのオープンソース版
市場にあるすべてのベクトルデータベースは、あなたのデータを平文で第三者に渡すことを要求します。XTraceはそうではありません。ドキュメントと埋め込みベクトルは、あなたのマシン上で暗号化されてから送信されます。サーバーは暗号文を保存・検索し、平文を見ることなく最近傍検索結果を計算します。検索中も、データはあなたのものです。
SDKには2つのモジュールがあります：
あなたのマシン XTrace サーバー
┌────────────────────────┐ ┌─────────────────────────┐
│ │ │ │
│ ドキュメント + クエリ │ │ 暗号文のみ保存 │
│ │ │ │ │
│ ▼ │ │ 暗号化ベクトルを検索 │
│ 埋め込み + 暗号化 │── 暗号文 ──▶│ （復号しない） │
│ （鍵はここに留まる） │ │ │
│ ▲ │ │ │
│ │ │◀─ 暗号文 ────│ 暗号化結果を返す │
│ 結果を復号 │ │ │
│ │ │ │
└────────────────────────┘ └─────────────────────────┘
秘密鍵は決して離れない ゼロ知識
XTraceは、ネットワークに何も触れる前に、すべてをあなたのマシン上で暗号化します。コンテンツは選択したモデルでローカルに埋め込まれ、結果のベクトルと生テキストの両方がそれぞれPaillier準同型暗号とAES-256で暗号化されます。サーバーは暗号文のみを保存・操作します。検索時もクエリは同じ方法で暗号化されます。秘密鍵はあなたの環境から決して離れず、サーバーは平文の1バイトも見ることはありません。暗号化を検証する
[!TIP] 🚀 無料アカウントをapp.xtrace.aiで作成して、APIキーと組織IDを取得してください。無料枠はレート制限がありますが、完全に機能します。
# ベースSDK
uv pip install xtrace-ai-sdk
# ローカル埋め込み対応（Sentence Transformers）
uv pip install "xtrace-ai-sdk[embedding]"
Python 3.11以上が必要です。
完全なドキュメントはdocs.xtrace.aiにあります。ローカルでビルドする場合：
cd docs && make html
ゼロから検索結果まで最速の方法：
uv pip install "xtrace-ai-sdk[cli]"
xtrace init # 認証情報と暗号化鍵の設定
xtrace kb create my-first-kb # ナレッジベースを作成（KB IDをメモ）
xtrace xvec load ./my-docs/ <KB_ID> # ドキュメントを暗号化してアップロード
xtrace xvec retrieve <KB_ID> "your query" # 検索
完全な非同期例：
import asyncio
from xtrace_sdk.x_vec.utils.execution_context import ExecutionContext
from xtrace_sdk.x_vec.crypto.key_provider import PassphraseKeyProvider
from xtrace_sdk.x_vec.data_loaders.loader import DataLoader
from xtrace_sdk.x_vec.inference.embedding import Embedding
from xtrace_sdk.integrations.xtrace import XTraceIntegration
from xtrace_sdk.x_vec.retrievers.retriever import Retriever
# One-time setup: generate your private cryptographic state and save it
provider = PassphraseKeyProvider("your-secret-passphrase")
ctx = ExecutionContext.create(
key_provider=provider,
homomorphic_client_type="paillier_lookup",
embedding_length=512,
key_len=1024,
path="data/exec_context",
)
embed = Embedding("sentence_transformer", "mixedbread-ai/mxbai-embed-large-v1", 512)
xtrace = XTraceIntegration(org_id="your_org_id", api_key="your_api_key")
async def main():
# Encrypt and store documents — content and vectors never leave in plaintext
loader = DataLoader(ctx, xtrace)
docs = [{"chunk_content": "XTrace encrypts your embeddings.", "meta_data": {}}]
vectors = [await embed.bin_embed(d["chunk_content"]) for d in docs]
index, db = await loader.load_data_from_memory(docs, vectors)
await loader.dump_db(db, index=index, kb_id="your_kb_id")
# Query with an encrypted vector — the server never sees the query in plaintext
retriever = Retriever(ctx, xtrace)
vec = await embed.bin_embed("How does XTrace protect my data?")
ids = await retriever.nn_search_for_ids(vec, k=3, kb_id="your_kb_id")
results = await retriever.retrieve_and_decrypt(ids, kb_id="your_kb_id")
for r in results:
print(r["chunk_content"])
asyncio.run(main())
このリポジトリは、自分で暗号化を検証できるように存在します。テストは完全にオフラインで実行され、XTraceアカウントは必要ありません：
uv pip install -e ".[dev]"
pytest tests/x_vec/
test_paillier_encryption.py と test_paillier_lookup_encryption.py は、暗号化/復号のラウンドトリップと、暗号文に対する準同型加算を検証します。これらはSDKがXTraceにデータを送信するときに使用するものと同じプリミティブです。秘密鍵はあなたのマシンから決して離れません。
コントリビューションを歓迎します。ガイドラインについてはCONTRIBUTING.mdを参照してください。
Apache 2.0 — LICENSEを参照してください。