DeepZotero
Zotero库的语义搜索。PDF被提取(文本、表格、图形)、分块、嵌入并存储在ChromaDB中。MCP服务器将索引作为13种工具公开给Claude Code(或任何MCP客户端),用于语义搜索、布尔搜索、表/图搜索、上下文扩展、引文图查找、索引和成本跟踪。
它提取了什么
- 文本 --具有重叠的节感知块,按文档节(摘要、方法、结果等)分类
- 表格 --通过Claude Haiku 4.5进行基于视觉的提取。每个表格都呈现为PNG格式,并转录为结构化的markdown(标题、行、脚注)。如果视力受损,则返回PyMuPDF启发式算法。
- 图 --通过字幕检测,提取为PNG,可通过字幕文本搜索。
需求
- Python 3.10+
- A. Gemini API密钥 用于嵌入(除非使用
embedding_provider: "local") - 一 无烟煤API键 用于基于视觉的表格提取(可选但推荐)
- 带PDF的Zotero安装
storage/
安装```bash
python -m venv .venv
.venv/Scripts/python.exe -m pip install -e .
对于视觉表提取:```bash
.venv/Scripts/python.exe -m pip install -e ".[vision]"
设置
1.配置```bash
mkdir -p ~/.config/deep-zotero
cp config.example.json ~/.config/deep-zotero/config.json
编辑 `~/.config/deep-zotero/config.json`:```json
{
"zotero_data_dir": "~/Zotero",
"chroma_db_path": "~/.local/share/deep-zotero/chroma",
"gemini_api_key": "YOUR_GEMINI_KEY",
"anthropic_api_key": "YOUR_ANTHROPIC_KEY"
}
所有其他字段都有合理的默认值。您还可以设置 GEMINI_API_KEY 和 ANTHROPIC_API_KEY 作为环境变量。
2.API密钥
Gemini(默认嵌入所需):
获取钥匙 Aistudio.google.com/app/apikey.将其设置为 gemini_api_key 在配置或 GEMINI_API_KEY env var.如果你不想使用Gemini,设置 "embedding_provider": "local" 使用ChromaDB内置的全MiniLM-L6-v2型号(无需API密钥,质量较低)。
拟人(提取视觉表时需要):
获取钥匙 console.anthropic.com.将其设置为 anthropic_api_key 在配置或 ANTHROPIC_API_KEY env var。没有此键,表仍然通过PyMuPDF启发式方法提取,但复杂表的准确性较低。视觉提取使用Claude Haiku 4.5的Anthropic Batch API,每张表的成本约为0.016美元,快速缓存降低了大批量的成本。
要完全禁用视觉提取,请执行以下操作:```json
{
"vision_enabled": false
}
### 3.为你的图书馆建立索引```bash
deep-zotero-index -v
要先测试子集,请执行以下操作:```bash
deep-zotero-index --limit 10 -v
这会读取Zotero SQLite数据库(只读,在Zotero打开时是安全的),从每个PDF中提取文本/表格/图形,对文本进行分块,通过Gemini嵌入,并将所有内容存储在ChromaDB中。
CLI选项:
|标志|描述|
|------|-------------|
| `--force` |删除并重建所有匹配项的索引|
| `--limit N` |仅索引N个项目|
| `--item-key KEY` |索引单个Zotero项目|
| `--title PATTERN` |标题上的正则表达式过滤器(不区分大小写)|
| `--no-vision` |跳过此运行的视觉表提取|
| `--config PATH` |使用其他配置文件|
| `-v` |调试日志记录|
索引器是增量的,它只处理索引中没有的项。使用 `--force` 变更后 `chunk_size`, `embedding_dimensions`,或 `ocr_language`.
您还可以通过以下方式从MCP客户端触发索引 `index_library` 工具。
### 4.注册MCP服务器
添加到您的克劳德代码设置(`~/.claude/settings.json`):```json
{
"mcpServers": {
"deep-zotero": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "deep_zotero.server"]
}
}
}
在Windows上:```json
{
"mcpServers": {
"deep-zotero": {
"command": "C:\path\to\.venv\Scripts\python.exe",
"args": ["-m", "deep_zotero.server"]
}
}
}
重新启动克劳德代码。所有13个工具都将可用。
______________________________________________________________________
## 配置参考
### 佐特罗
|字段|默认值|描述|
|---|---|---|
| `zotero_data_dir` | `~/Zotero` |Zotero数据目录的路径(包含 `zotero.sqlite` 和 `storage/`) |
| `chroma_db_path` | `~/.local/share/deep-zotero/chroma` |ChromaDB索引存储在磁盘上的位置|
### 嵌入
|字段|默认值|描述|
|---|---|---|
| `embedding_provider` | `"gemini"` | `"gemini"` 对于Gemini API, `"local"` 适用于ChromaDB内置的全MiniLM-L6-v2(无需密钥)|
| `embedding_model` | `"gemini-embedding-001"` |Gemini型号名称(仅在提供程序为 `"gemini"`) |
| `embedding_dimensions` | `768` |输出向量维度。 `gemini-embedding-001` 支持64-3072。更改需要 `--force` 重新索引|
| `gemini_api_key` | `null` |回落到 `GEMINI_API_KEY` 有人是。
| `embedding_timeout` | `120.0` |嵌入API调用的超时时间(秒)|
| `embedding_max_retries` | `3` |嵌入调用失败的最大重试次数|
### 分块
|字段|默认值|描述|
|---|---|---|
| `chunk_size` | `400` |以令牌为单位的目标块大小(~4个字符/令牌)。更改需要 `--force` 重新索引|
| `chunk_overlap` | `100` |令牌中连续块之间的重叠|
### 视觉
|字段|默认值|描述|
|---|---|---|
| `vision_enabled` | `true` |在索引过程中启用视觉表提取|
| `vision_model` | `"claude-haiku-4-5-20251001"` |表转录的拟人模型|
| `anthropic_api_key` | `null` |回落到 `ANTHROPIC_API_KEY` 有人是。
### 重排序
|字段|默认值|描述|
|---|---|---|
| `rerank_enabled` | `true` |启用综合分数重新排名|
| `rerank_alpha` | `0.7` |相似指数(0-1)。更低=元数据影响更大|
| `rerank_section_weights` | `null` |覆盖默认截面权重|
| `rerank_journal_weights` | `null` |覆盖默认日记账四分位数权重|
| `oversample_multiplier` | `3` |重新评级前的超额系数|
| `oversample_topic_factor` | `5` |附加因素 `search_topic` |
| `stats_sample_limit` | `10000` |采样的最大块数 `get_index_stats` |
### 光学字符识别
|字段|默认值|描述|
|---|---|---|
| `ocr_language` | `"eng"` |扫描页面的细分语言代码(`"fra"`, `"deu"`等等)。更改需要 `--force` 重新索引|
### OpenAlex
|字段|默认值|描述|
|---|---|---|
| `openalex_email` | `null` |OpenAlex礼貌池的电子邮件(10个请求/秒vs 1个请求/s)。回落到 `OPENALEX_EMAIL` 有人是。
______________________________________________________________________
## MCP工具
### 语义搜索
**`search_papers`** --段落级语义搜索。返回与周围上下文匹配的文本,按综合得分(相似度×节权重×期刊权重)重新排序。支持 `required_terms` 为了将语义搜索与精确的单词匹配相结合,每个术语都必须作为一个完整的单词出现在文章中。
参数: `query`, `top_k` (1-50), `context_chunks` (0-3), `year_min`, `year_max`, `author`, `tag`, `collection`, `chunk_types` (文本/图形/表格), `section_weights`, `journal_weights`, `required_terms` (文章中必须出现的单词列表)。
**`search_topic`** --论文级主题搜索,按文档进行重复数据消除。按纸张分组,按平均值和最佳复合相关性得分。
参数: `query`, `num_papers` (1-50), `year_min`, `year_max`, `author`, `tag`, `collection`, `chunk_types`, `section_weights`, `journal_weights`.
**`search_tables`** --对表内容(标题、单元格、标题)进行语义搜索。以markdown形式返回表。
参数: `query`, `top_k` (1-30), `year_min`, `year_max`, `author`, `tag`, `collection`, `journal_weights`.
**`search_figures`** --对图形标题进行语义搜索。返回图形元数据和提取的PNG的路径。
参数: `query`, `top_k` (1-30), `year_min`, `year_max`, `author`, `tag`, `collection`.
### 布尔搜索
**`search_boolean`** --通过Zotero的原生全文索引进行精确的单词匹配。返回与AND/OR单词查询匹配的论文(不是段落)。没有短语搜索,没有词干。
参数: `query` (空格分隔的术语), `operator` (和/或), `year_min`, `year_max`.
### 上下文扩展
**`get_passage_context`** --围绕以下段落展开上下文 `search_papers`。对于表格结果,请通过 `table_page` 和 `table_index` 查找引用表格的正文。
参数: `doc_id`, `chunk_index`, `window` (1-5), `table_page`, `table_index`.
### 引文图(OpenAlex)
要求文档在Zotero中有DOI。
**`find_citing_papers`** --引用特定文件的论文。参数: `doc_id`, `limit` (1-100).
**`find_references`** --文件引用的论文。参数: `doc_id`, `limit` (1-100).
**`get_citation_count`** --引文和参考文献计数。参数: `doc_id`.
### 指标管理
**`index_library`** --从MCP客户端触发索引。参数: `force_reindex`, `limit`, `item_key`, `title_pattern`, `no_vision`.
**`get_index_stats`** --文档/块/表/图计数、章节覆盖率、期刊覆盖率。
**`get_reranking_config`** --当前重新排序权重和有效覆盖值。
**`get_vision_costs`** -愿景API批量使用和成本摘要。参数: `last_n` (要显示的最新条目)。
______________________________________________________________________
## 重排序
搜索结果评分:```
composite_score = similarity^alpha * section_weight * journal_weight
默认截面权重:
| 截面 | 重量 |
|---|---|
| 结果 | 1.0 |
| 结论 | 1.0 |
| 表 | 0.9 |
| 方法 | 0.85 |
| 摘要 | 0.75 |
| 背景 | 0.7 |
| 未知 | 0.7 |
| 讨论 | 0.65 |
| 引言 | 0.5 |
| 序言 | 0.3 |
| 附录 | 0.3 |
| 参考文献 | 0.1 |
默认日记账权重:Q1=1.0,Q2=0.85,Q3=0.65,Q4=0.45。
通过以下方式覆盖每次呼叫 section_weights 和 journal_weights 参数。将某个部分设置为0以将其排除。完全禁用重新分级 "rerank_enabled": false.
共享筛选器参数
| 参数 | 类型 | 说明 |
|---|---|---|
author |
string | 与作者姓名不区分大小写的子字符串匹配 |
tag |
string | 与Zotero标签不区分大小写的子字符串匹配 |
collection |
string | 与集合名称不区分大小写的子字符串匹配 |
year_min / year_max |
int | 出版年份范围 |
section_weights |
dict | 覆盖此调用的节权重 |
journal_weights |
dict | 覆盖日志四分位数权重 |
required_terms |
列表 | 文章中需要精确的整词匹配(search_papers 仅) |
调试查看器
tools/debug_viewer.py 是一个PyQt6浏览器,用于检查ChromaDB索引——查看论文、表格(渲染的markdown与PDF)、图形和单个块。bash
.venv/Scripts/python.exe tools/debug_viewer.py