AI Classifier - 功能介绍与实现原理

作为科研工作者，你是否曾为管理大量文献而头疼？面对成百上千篇论文，如何高效地将它们分类到合适的文件夹成为一个难题。AI Classifier 正是为解决这一问题而生的 Zotero 插件，它利用大语言模型（LLM）实现智能文献分类，让你的文献管理效率大幅提升。

本文将详细介绍 AI Classifier 的核心功能，并深入讲解每个功能的实现原理，帮助你更好地理解插件的工作机制。

一、核心功能概览

AI Classifier 提供以下核心功能：

功能	说明
📂 智能归类	AI 自动阅读文献标题、摘要、关键词，按置信度阈值自动归类
💾 保存/恢复结构	备份当前分类结构，随时恢复
📤 导出数据	导出标题、摘要、关键词为 JSON
📥 导入层级	从 TXT 文件批量创建文件夹结构
🛑 停止归类	随时中断正在进行的分类任务
🛡️ 隐私优先	API Key 仅保存在本地，不上传服务器

二、功能详解与实现原理

2.1 智能归类（核心功能）

这是 AI Classifier 最核心的功能。它利用 LLM 理解文献内容，自动将文献分类到预设的文件夹中。

实现原理

第一步：获取文献信息

插件通过 Zotero API 获取用户选中文献的以下信息：

标题（Title）
摘要（Abstract）
关键词（Keywords）

这些信息构成了 LLM 理解文献内容的基础。

第二步：构建提示词（Prompt）

插件将用户配置的分类目录结构和文献信息组合成提示词，发送给 LLM。提示词的核心逻辑如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
你是一个文献分类助手。以下是待分类文献的信息：
标题：{title}
摘要：{abstract}
关键词：{keywords}

可用的分类目录结构如下：
{folder_structure}

请根据文献内容，从上述目录中选择最合适的分类路径。
返回格式要求：JSON格式，包含以下字段：
- "path": 最合适的分类路径
- "confidence": 置信度（0-1之间的浮点数）
- "reason": 简要说明分类理由

第三步：调用 LLM API

插件通过 HTTP 请求调用用户配置的 LLM API（如 SiliconFlow、OpenAI 等），发送构建好的提示词，获取分类结果。

API 调用使用标准的 OpenAI 兼容格式：

1
2
3
4
5
6
7
{
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "messages": [
    {"role": "user", "content": "..."}
  ],
  "temperature": 0.1
}

第四步：解析响应与置信度判断

LLM 返回分类结果后，插件解析 JSON 响应，获取分类路径和置信度。

关键设计：置信度阈值机制

用户可以配置置信度阈值（默认 0.7）。只有当 LLM 返回的置信度高于阈值时，插件才会自动移动文献；否则，文献保持原位，分类结果仅记录在日志中。

这一设计有重要意义：

避免错误分类：低置信度意味着 AI 不确定，强制归类可能导致错误
用户可控：通过调整阈值，用户可以在"自动化程度"和"准确率"之间权衡
渐进优化：用户可以先处理高置信度结果，再回头检查低置信度结果

第五步：执行分类

根据分类结果，插件调用 Zotero API 将文献移动到对应的文件夹：

1
2
// 移动文献到目标集合
await item.moveToCollection(collectionPath);

技术亮点

批量处理：支持一次性选中多篇文献，串行调用 LLM API（避免并发过高导致 API 限流）
增量进度：每完成一篇文献的分类，立即更新 UI，用户可以看到实时进度
错误容忍：单篇文献分类失败不影响其他文献，继续处理后续文献
异步任务：分类过程在后台运行，不阻塞 Zotero 主界面

2.2 保存与恢复分类结构

这一功能用于备份和恢复你的文献分类体系，防止因误操作导致分类结构丢失。

实现原理

保存结构

插件遍历 Zotero 中的所有收藏夹（Collections），递归提取文件夹层级结构，并序列化保存为 JSON 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// 伪代码：保存结构
function saveStructure() {
  const collections = Zotero.Collections.get();
  const structure = traverseCollections(collections, null);
  const json = JSON.stringify(structure, null, 2);
  saveToFile(json, backupPath);
}

// 递归遍历收藏夹
function traverseCollections(collections, parentId) {
  return collections
    .filter(c => c.parentID === parentId)
    .map(c => ({
      name: c.name,
      children: traverseCollections(collections, c.id)
    }));
}

恢复结构

读取备份 JSON 文件，递归创建收藏夹：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// 伪代码：恢复结构
function restoreStructure(json) {
  const structure = JSON.parse(json);
  createCollections(structure, null);
}

function createCollections(nodes, parentId) {
  nodes.forEach(node => {
    const collection = Zotero.Collections.create({
      name: node.name,
      parentID: parentId
    });
    if (node.children) {
      createCollections(node.children, collection.id);
    }
  });
}

注意事项

恢复结构：采用增量追加模式，只会补充备份中存在但当前不存在的文件夹，不会删除现有的分类结构，也不会影响已分类的文献
从 TXT 导入：会清空现有所有收藏夹后重建（文献本身不会被删除）
导入前插件会提示确认，请谨慎操作

2.3 导出文献数据

这一功能可以将文献的标题、摘要、关键词导出为 JSON 文件，方便后续分析或迁移。

实现原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// 伪代码：导出数据
function exportData(type) {
  const items = Zotero.Items.getAll();
  const data = items.map(item => {
    switch(type) {
      case 'title': return item.getField('title');
      case 'abstract': return item.getField('abstractNote');
      case 'keywords': return item.getTags().map(t => t.tag);
    }
  });
  saveToFile(JSON.stringify(data, null, 2), exportPath);
}

导出格式示例（标题）：

1
2
3
4
5
[
  "Deep Learning for Scientific Discovery",
  "A Survey of Natural Language Processing",
  "Quantum Computing: Principles and Applications"
]

2.4 从 TXT 导入层级

这一功能允许用户通过文本文件批量创建文件夹结构，非常适合一次性建立完整的分类体系。

实现原理

TXT 文件格式

插件支持层级缩进格式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
1. 物理学
1.1 量子力学
1.2 热力学
1.3 相对论
1.3.1 广义相对论
1.3.2 狭义相对论
2. 化学
2.1 有机化学
2.2 无机化学
2.3 分析化学

缩进可以使用空格或制表符，数字前缀用于排序。

解析逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// 伪代码：解析 TXT
function parseHierarchy(text) {
  const lines = text.split('\n');
  const stack = [];
  
  lines.forEach(line => {
    const match = line.match(/^(\s*)(\d+\.)?\s*(.+)/);
    if (!match) return;
    
    const indent = match[1].length;
    const name = match[3];
    const level = Math.floor(indent / 2) + 1;
    
    // 根据缩进级别确定父节点
    while (stack.length >= level) stack.pop();
    
    const node = { name, children: [] };
    if (stack.length === 0) {
      root.push(node);
    } else {
      stack[stack.length - 1].children.push(node);
    }
    stack.push(node);
  });
  
  return root;
}

创建收藏夹

解析完成后，递归调用 Zotero API 创建收藏夹：

1
2
3
4
5
6
7
8
9
function createCollections(nodes, parentId) {
  nodes.forEach(node => {
    const collection = Zotero.Collections.create({
      name: node.name,
      parentID: parentId
    });
    createCollections(node.children, collection.id);
  });
}

注意事项

导入层级会清空现有所有收藏夹（包括其中的文献，但文献本身不会被删除）
导入前插件会提示确认，请谨慎操作

2.5 停止分类任务

在处理大量文献时，用户可能需要中途停止分类进程。这一功能可以安全地中断正在进行的分类任务。

实现原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// 使用标志位控制任务
let isStopping = false;

async function classifyPapers(items) {
  for (const item of items) {
    if (isStopping) {
      console.log("分类任务已停止");
      break;
    }
    
    await classifyOnePaper(item);
    updateProgress();
  }
}

function stopClassification() {
  isStopping = true;
}

设计考量

优雅停止：不是强制终止线程，而是设置标志位，让当前批次完成后自然退出
状态重置：停止后需要重置标志位，以便下次分类任务可以正常运行

2.6 隐私优先：本地存储

AI Classifier 在隐私设计上非常谨慎，确保用户的 API Key 和文献数据安全。

实现原理

配置文件存储位置

所有配置信息（包括 API Key）保存在 Zotero 数据目录下的 JSON 文件中：

操作系统	路径
Windows	`%APPDATA%\Zotero\zotero_ai_config.json`
macOS	`~/Library/Application Support/Zotero/zotero_ai_config.json`
Linux	`~/.config/zotero/zotero_ai_config.json`

数据流向

1
2
3
用户 → 插件 → LLM API → 返回结果
         ↓
    本地配置文件（API Key）

关键点：

API Key 只存在于本地配置文件，不经过任何第三方服务器
调用 LLM API 时，插件直接与 API 服务商通信（如 SiliconFlow、OpenAI）
插件本身不搭建任何后端服务，不收集任何用户数据
文献内容（标题、摘要、关键词）仅在分类过程中发送给 LLM API，不保存副本

三、配置指南

3.1 配置文件结构

zotero_ai_config.json 包含以下字段：

1
2
3
4
5
6
7
8
{
  "apiUrl": "https://api.siliconflow.cn/v1/chat/completions",
  "apiKey": "your-api-key-here",
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "logPath": "/path/to/log/file.log",
  "confidenceThreshold": 0.7,
  "customPrompt": ""
}

3.2 支持的 LLM 服务商

理论上支持所有兼容 OpenAI API 格式的服务商，常见选择：

SiliconFlow：国内访问速度快，价格实惠
OpenAI：官方服务，质量有保障
Anthropic：Claude 系列模型
本地部署：Ollama、LM Studio 等本地模型

3.3 提示词自定义

在「设置」→「提示词配置」中，用户可以自定义发送给 LLM 的提示词。高级用户可以根据自己的学科特点优化提示词，提升分类准确率。

四、快速入门

4.1 安装步骤

前往 GitHub Releases 下载最新 .xpi 文件
打开 Zotero，点击工具 → 附加组件
点击齿轮图标 → 从文件安装附加组件
选中下载的 .xpi 文件
重启 Zotero

4.2 首次配置

点击工具 → AI Classifier → 设置日志保存位置，选择日志保存路径
点击工具 → AI Classifier → 设置 → API 参数配置
填写以下信息：
- API URL：如 https://api.siliconflow.cn/v1/chat/completions
- API Key：你的密钥
- Model Name：如 Qwen/Qwen2.5-7B-Instruct
点击「测试连接」，确认成功后保存

4.3 完整工作流程

第一步：创建分类层级

新建 TXT 文件，定义你的分类结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
1. 机器学习
1.1 深度学习
1.2 强化学习
1.3 自然语言处理
2. 计算机视觉
2.1 图像分类
2.2 目标检测
2.3 图像分割
3. 物理学
3.1 量子力学
3.2 流体力学

💡 提示：如果你不确定如何构建分类结构，可以先使用插件的「导出」功能将文献库信息（标题、摘要等）导出，然后提交给 AI，让 AI 根据你的文献内容推荐合理的分类层级。这样比自己冥思苦想更加高效。

第二步：导入层级

点击 AI Classifier → 从 TXT 导入层级，选择上述 TXT 文件。

第三步：选择文献并分类

在 Zotero 中选中多篇待分类文献
点击 AI Classifier → LLM 模型文献归类
设置置信度阈值（如 0.7）
开始分类，观察进度

第四步：备份结构

重要操作前，点击 保存当前分类结构 备份。

五、常见问题

Q1: 分类结果不准确怎么办？

调整置信度阈值，降低阈值可以让更多文献被分类，但可能增加错误率
自定义提示词，提供更详细的分类指导
使用更强大的 LLM 模型

Q2: 分类速度慢怎么办？

选择响应更快的 API 服务商（如 SiliconFlow）
使用更小的模型（如 Qwen2.5-3B）
减少单次分类的文献数量

Q3: API 调用失败怎么办？

检查 API Key 是否正确
检查网络连接
查看日志文件（工具 → AI Classifier → 日志查看器）排查错误

六、总结

AI Classifier 通过将大语言模型与 Zotero 文献管理深度结合，实现了科研文献的智能分类。它不仅功能完善，而且在实现上充分考虑了用户隐私、数据安全和使用体验。

理解每个功能的实现原理，有助于你更好地使用插件，并根据实际需求进行调优。希望本文能帮助你充分发挥 AI Classifier 的威力，让文献管理变得更加轻松高效。