内容
<div align="center">
<br>
<h1>
<img src="https://raw.githubusercontent.com/kyrillosishak/Domicile/main/assets/logo.png" alt="Domicile Logo" height="120" align="center"/>
</h1>
**您的数据，居所于您的设备。**
<br>
本地隐私保护，在浏览器中 — 向量数据库、RAG 和本地 LLM。
所有处理过程都在客户端进行，零 egress。
[](https://www.npmjs.com/package/@kyrillosishak/domicile)
[](./LICENSE)
</div>
---
## 为什么选择 Domicile？
Domicile 是一个私有的 AI 栈 — 向量数据库、RAG 和本地 LLM，完全在浏览器中运行。提供类似本地部署的数据托管和权限保护，无需本地基础设施。您的文档永远不会离开其合法的存储位置。
- **私密**: 数据永远不会离开设备 — 零 egress，零第三方处理器
- **快速**: WebGPU 加速，WASM SIMD 备用
- **免费**: 零云成本，无需 API 密钥，无需按席位收费
- **完整**: 向量数据库 + 嵌入 + 双 LLM + RAG，附带引用
- **离线**: 初始加载后，无需互联网即可运行
## 快速开始
```bash
npm install @kyrillosishak/domicile
```
```typescript
import Domicile from '@kyrillosishak/domicile';
// 一个私有的、浏览器端的托管层
const db = new Domicile({
storage: { dbName: 'matter-files' },
index: { dimensions: 384, metric: 'cosine' },
embedding: { model: 'Xenova/all-MiniLM-L6-v2', device: 'webgpu' },
});
await db.initialize();
await db.insert({
text: '特权通信 — 律师工作产品',
metadata: { matter: 'M-204', privilege: 'true' },
});
const results = await db.search({ text: '工作产品摘要', k: 5 });
console.log(results);
```
## 功能
- **向量数据库**: IndexedDB 中的持久客户端存储，带有纯 TypeScript HNSW 图索引。可容纳和搜索 10 万+ 文档，支持 cosine、euclidean 或 dot 指标 — 真实的相似度得分，不重建的删除 — 所有数据均在设备上。
- **本地嵌入**: Transformers.js，支持 WebGPU 加速和 WASM 备用。模型权重缓存在设备上，因此重复查询永远不会到达网络。
- **双 LLM 运行时**: WebLLM 用于 GPU 快速推理，Wllama 用于 CPU 可移植性 — 自动备用，确保在任何工作站上都能生成内容。
- **RAG with 引用**: 答案基于您的源文档，引用链接到每个声明所依据的文档 — 可审计，非黑盒。
- **MCP 集成**: 将您的托管层暴露为 Model Context Protocol 工具 — 将 Domicile 集成到 Claude Desktop 和您的团队已经构建的代理栈中。
- **设计为本地**: 数据存储在设备上 — 无云 egress，无第三方处理器，无存储位置漂移。边界是架构性的，不是配置问题。
## 适用对象
**律师事务所和法律团队** — 敏感的案件文件，特权通信和客户数据永远不会离开工作站。Domicile 在本地运行 RAG 和生成，因此 attorney-client 特权永远不会通过第三方云路由。按照设计符合 GDPR 标准，可离线工作。
**集成和基础设施团队** — 为需要本地保证但无需本地资本支出的客户提供的托管层。将它集成到他们的应用程序中，配置存储位置，然后离开 — 无需运行服务器，也无需保护数据平面。
## 核心功能
### 向量搜索
```typescript
// 带有元数据过滤的检索
const results = await db.search({
text: '赔偿条款',
k: 10,
filter: { field: 'matter', operator: 'eq', value: 'M-204' },
});
for (const r of results) {
console.log(r.score.toFixed(3), r.metadata);
}
// 检查托管状态
const stats: IndexStats = await db.stats();
console.log(stats.vectorCount, stats.memoryUsage);
```
### RAG Pipeline
```typescript
import { RAGPipelineManager, WllamaProvider } from '@kyrillosishak/domicile';
const llm = new WllamaProvider({ model: '...' });
const rag = new RAGPipelineManager(db, llm, embedding);
// 提问基于您的文档
const result = await rag.query('Summarize the position.', {
topK: 3,
generateOptions: { maxTokens: 256, temperature: 0.7 },
});
console.log(result.answer);
console.log(result.sources); // 引用源文档
```
### MCP 集成
```typescript
import { MCPServer } from '@kyrillosishak/domicile';
// 将您的托管层暴露为 AI 代理的工具
const mcp = new MCPServer(db, rag);
const tools: MCPTool[] = mcp.getTools();
// → [search, insert, rag_query, ...]
// 连接到 Claude Desktop 或任何 MCP 感知代理
mcp.serve({ transport: 'stdio' });
```
## 架构
一个分层的、设计为本地的栈。每个层都是可替换的，无需服务器即可运行。数据流向下；答案流向上 — 所有操作都在设备上。
- **界面**: 您的应用程序通过干净的 TypeScript API 或通过 MCP 与 AI 代理通信 — Claude Desktop、ChatGPT，任何支持该协议的系统。
- **智能**: RAG Pipeline Manager 协调检索和生成，带有 WebLLM 和 Wllama 运行时以及自动 GPU 到 CPU 备用。
- **检索**: Transformers.js 生成嵌入；纯 TS HNSW 索引返回最近的邻居，带有真实的分数。BM25 稀疏索引与密集索引通过 reciprocal-rank 融合，cross-encoder reranker 锐化 top-k — 所有操作都经过元数据过滤。
- **托管**: IndexedDB 存储管理器，带有 quota-aware 清除和 JSON/binary 导出导入，用于迁移和客户端交接。
- **加速**: 当 WebGPU 可用时使用 GPU 计算，否则使用 WASM SIMD 备用，带有工作线程池进行批处理并行。
- **可靠性**: 类型化的错误层次结构，LRU 缓存，内存管理器和内置基准测试运行器来衡量所有内容。
```mermaid
graph TB
subgraph "界面"
APP[用户应用程序]
MCP[MCP 接口]
end
subgraph "智能"
API[向量数据库 API]
RAG[RAG Pipeline 管理器]
end
subgraph "检索"
TJS[Transformers.js]
CACHE[模型缓存]
end
subgraph "LLM 层"
WLLAMA[wllama - WASM]
WEBLLM[WebLLM - WebGPU]
end
subgraph "索引层"
HNSW[HNSW 图索引]
BM25[BM25 稀疏索引]
end
subgraph "托管"
IDB[IndexedDB]
STORE[存储管理器]
end
APP --> API
MCP --> API
API --> RAG
API --> HNSW
RAG --> TJS
RAG --> WLLAMA
RAG --> WEBLLM
TJS --> CACHE
HNSW --> STORE
STORE --> IDB
```
## 性能
可从 `domicile bench` 复制 — 相同的测试套件用于构建测试。在 Linux/server CPU (Node) 上测量；浏览器 WebGPU 运行将有所不同。
| 操作 | 延迟 | 吞吐量 / 质量 | 备注 |
|-----------|---------|----------------------|-------|
| 搜索 (10K 向量, 128-dim cosine) | p50 2.4ms / p99 7ms | recall@10 = 0.91 | 纯 TS HNSW，暖缓存 |
| 搜索 (1K 向量, 128-dim cosine) | p50 1.4ms / p99 1.8ms | recall@10 = 1.00 | 非重建删除 <0.01ms |
| 引用准确性 (法律已知答案语料库) | — | recall@3 = 0.92 | 密集 + 混合 + 重新排序检索 |
| RAG 查询 (完整管道) | 检索 + 生成 | 流式传输 | 本地 LLM，绑定到浏览器 |
*复制：`npm run build && node dist/cli/index.js bench`*
## 开发
```bash
# 安装依赖
npm install
# 运行测试
npm test
# 在监视模式下运行测试
npm run test:watch
# 运行集成测试（需要网络）
npm run test:integration
# 构建库
npm run build
# 类型检查
npm run type-check
# 运行基准测试
npm run benchmark
```
## 浏览器支持
- **Chrome/Edge**: 90+ (WebGPU: 113+)
- **Firefox**: 88+ (WebGPU: 暂不支持)
- **Safari**: 14+ (WebGPU: 暂不支持)
**要求：**
- IndexedDB 支持
- WebAssembly 支持
- ES2020+ JavaScript
**可选：**
- WebGPU 用于加速推理
- SharedArrayBuffer 用于多线程
## 路线图
- Python 绑定 (PyScript)
- React hooks 包
- 混合搜索 (密集 + 稀疏)
- 多模态嵌入 (CLIP)
- 浏览器中的量化
## 贡献
欢迎贡献。请打开问题或 PR。
## 许可证
MIT © 2026
---
<div align="center">
**[文档](./docs/QUICKSTART.md)** • **[示例](./examples/README.md)** • **[GitHub](https://github.com/kyrillosishak/Domicile)**
为注重隐私的法律和集成团队构建
</div>
