XTraceAI/xtrace-sdk

# 什么是 XTrace？ 市场上的每一个向量数据库都要求您以明文形式将数据交给第三方。XTrace 不需要。您的文档和嵌入向量在传输之前会在**您的设备上**进行加密。服务器存储和搜索密文 —— 它在从未看到明文的情况下计算最近邻结果。您的数据始终属于您，即使在搜索期间也是如此。 该 SDK 有两个模块： - **x-vec** —— 加密的向量搜索。通过端到端加密存储和查询文本块。 - **x-mem** —— AI agents 的加密代理记忆（即将推出）。 ## 工作原理 ``` Your Machine XTrace Server ┌────────────────────────┐ ┌─────────────────────────┐ │ │ │ │ │ Documents + Queries │ │ Stores only ciphertext │ │ │ │ │ │ │ ▼ │ │ Searches over │ │ Embed + Encrypt │── ciphertext ─▶│ encrypted vectors │ │ (keys stay here) │ │ (never decrypts) │ │ ▲ │ │ │ │ │ │◀─ ciphertext ──│ Returns encrypted │ │ Decrypt results │ │ results │ │ │ │ │ └────────────────────────┘ └─────────────────────────┘ Secret key never leaves Zero knowledge ``` XTrace 在任何内容接触网络之前，会在您的设备上对所有内容进行加密。您的内容在本地使用您选择的模型进行嵌入，生成的向量和原始文本分别使用 Paillier 同态加密和 AES-256 进行加密。服务器仅存储和操作密文。当您进行搜索时，您的查询也会以相同方式加密。密钥永远不会离开您的环境，服务器永远看不到一个字节的明文。[验证加密](#verify-the-encryption) # 快速开始 ## 安装 ``` # Base SDK uv pip install xtrace-ai-sdk # 支持 local embedding (Sentence Transformers) uv pip install "xtrace-ai-sdk[embedding]" ``` 需要 Python 3.11+。 ## 文档 完整文档请访问 [docs.xtrace.ai](https://docs.xtrace.ai)，或在本地构建： ``` cd docs && make html ``` ## CLI 从零开始获得搜索结果的最快方式： ``` uv pip install "xtrace-ai-sdk[cli]" xtrace init # set up credentials + encryption keys xtrace kb create my-first-kb # create a knowledge base (note the KB ID) xtrace xvec load ./my-docs/ # encrypt and upload documents xtrace xvec retrieve "your query" # search ``` ## 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 # 一次性设置：生成您的私有加密状态并保存 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](CONTRIBUTING.md)。 # 许可证 Apache 2.0 —— 详见 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, Embedding, LLM记忆, Python SDK, RAG, 加密向量数据库, 同态加密, 向量搜索, 密文检索, 开源, 数据防泄露, 文档安全, 文档结构分析, 本地加密, 机密计算, 私有化部署, 端到端加密, 网络安全, 计算机取证, 逆向工具, 防御规避, 隐私保护, 隐私计算, 零知识证明