什么是 XTrace？

市场上的每一个向量数据库都要求你将数据以明文形式交给第三方。XTrace 不会。你的文档和嵌入向量在你的机器上就被加密，然后才传输任何内容。服务器存储并在密文上执行搜索——它计算最近邻结果，却从未见过明文。即使搜索期间，你的数据也始终属于你。

SDK 包含两个模块：

x-vec — 加密向量搜索。使用端到端加密存储和查询文本块。
x-mem — AI 智能体的加密记忆（即将推出）。

工作原理

    你的机器                                  XTrace 服务器
┌────────────────────────┐                ┌─────────────────────────┐
│                        │                │                         │
│  文档 + 查询            │                │  仅存储密文              │
│         │              │                │                         │
│         ▼              │                │  在加密向量上执行搜索    │
│  嵌入 + 加密            │── 密文 ────────▶│  (从不解密)              │
│  (密钥留在此处)         │                │                         │
│         ▲              │                │                         │
│         │              │◀── 密文 ────────│  返回加密结果            │
│  解密结果               │                │                         │
│                        │                │                         │
└────────────────────────┘                └─────────────────────────┘
  密钥从不离开你的环境                        零知识

XTrace 在一切触及网络之前，就在你的机器上加密所有内容。你的内容由你选择的模型在本地嵌入，生成的向量和原始文本分别使用 Paillier 同态加密和 AES-256 加密。服务器仅存储和处理密文。当你搜索时，你的查询也以相同方式加密。密钥从不离开你的环境，服务器永远看不到一个明文字节。验证加密机制

快速开始

[!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

CLI

从零到搜索成果最快的方式：

uv pip install "xtrace-ai-sdk[cli]"

xtrace init                                    # 设置凭证 + 加密密钥
xtrace kb create my-first-kb                   # 创建知识库（记下知识库 ID）
xtrace xvec load ./my-docs/ <KB_ID>            # 加密并上传文档
xtrace xvec retrieve <KB_ID> "your query"      # 搜索

Python SDK

完整的异步示例：

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。

xtrace-sdk

最受欢迎