ContextWeave 是一个企业私有知识库和问答系统。用户上传文档，系统完成解析和索引，之后可以直接向知识库提问。
- 支持 PDF、Word、TXT 等常见文件。
- 上传中断后可以继续上传，不必从头开始。
- 同时使用关键词和向量语义检索。
- 用 Cross-Encoder 对候选结果重新排序。
- 命中小子块后，自动补回对应的父级上下文。
- 聊天回答保留引用，历史记录也能查看引用。
- 关键词和向量两条检索路径都遵守用户、组织和公开文档权限。
文档 -> 子块 -> BM25 + HNSW -> RRF -> Cross-Encoder
-> 父级上下文 -> Dynamic Top-K -> 带引用的回答
当前默认值：
- BM25 权重：
0.25 - HNSW 权重：
1.0 - 每条分支最多召回：
100条 - 送入重排的候选：
20条 - 父块大小：
2048字符 - 子块大小：
512字符，重叠100字符
这些值来自当前本地实验中表现最好的组合。它们仍然可以通过环境变量修改，正式上线前应在更大的真实数据集上再次验证。
环境要求：Windows 11、WSL2、Docker、Java 17、Maven、Node.js 18.20+ 和 pnpm 8.7+。
- 复制
.env.example为.env，填写数据库、服务和模型密钥。不要提交.env。 - 启动本地服务：
powershell -ExecutionPolicy Bypass -File .\scripts\start-local.ps1- 打开聊天页面：
http://localhost:9527/#/chat - 使用完毕后停止服务：
powershell -ExecutionPolicy Bypass -File .\scripts\stop-local.ps1修改 Java 后，可以先编译触发热加载：
mvn -q -DskipTests compile| 服务 | 作用 |
|---|---|
| Spring Boot | API、权限、检索和聊天 |
| Vue 3 | 网页界面 |
| MySQL | 用户、文件和持久化聊天记录 |
| Redis | 会话、短期聊天状态和断点续传状态 |
| Elasticsearch | BM25 和 HNSW 检索 |
| Kafka | 后台文档处理 |
| MinIO | 源文件和上传分片 |
评测使用 SciFact/NFCorpus 的 48 条固定查询。它适合比较代码改动，不是完整 BEIR 榜单，也不代表生产环境一定达到相同效果。
| 检索方式 | Recall@5 | Recall@10 | MRR@10 | NDCG@10 |
|---|---|---|---|---|
| BM25 | 0.4910 | 0.5111 | 0.7339 | 0.6313 |
| HNSW KNN | 0.5326 | 0.5799 | 0.8201 | 0.7264 |
| HNSW KNN + 重排 | 0.5368 | 0.5889 | 0.8492 | 0.7509 |
| 等权混合 + 重排 | 0.5325 | 0.5700 | 0.8408 | 0.7365 |
调过权重的混合 + 重排（0.25:1.0） |
0.5441 | 0.5965 | 0.8492 | 0.7569 |
等权融合时，BM25 对前 20 条重排候选的影响太大，会把一部分有价值的语义结果挤出去。把 BM25:KNN 调为 0.25:1.0 后，这个问题在当前评测集上得到改善。
父子分块实验中，父块 2048 字符是目前测试组合里比较平衡的选择：Recall@5 为 0.5641，Dynamic Top-K 平均选择 7.04 条结果。父块 4096 的测试在 embedding 请求阶段超时，因此没有计入结果。
详细的、不包含查询原文的报告见 benchmarks/retrieval/reports。
CONTEXTWEAVE_RETRIEVAL_RRF_BM25_WEIGHT=0.25
CONTEXTWEAVE_RETRIEVAL_RRF_KNN_WEIGHT=1.0
CONTEXTWEAVE_RERANK_MAX_CANDIDATES=20
CONTEXTWEAVE_RERANK_TOP_N=10
FILE_PARSING_PARENT_CHUNK_SIZE=2048mvn test
python -m unittest discover benchmarks\retrieval -p 'test_*.py'前端类型检查：
Set-Location frontend
pnpm typecheckApache License 2.0，详见 LICENSE。