核心用法
Zettel Link 是一套面向 Obsidian 知识库的语义化笔记管理工具链，通过 Python 脚本实现笔记的向量化嵌入、语义搜索与关联发现。完整工作流分为三步：首先运行 config.py 配置嵌入模型（默认 Ollama 本地 mxbai-embed-large，可选 OpenAI/Gemini），其次运行 embed.py 对指定目录建立增量嵌入缓存，最后通过 search.py 执行语义查询或 link.py 发现笔记间的潜在关联。
嵌入缓存采用 JSON 格式存储于 .embeddings/embeddings.json，支持基于文件修改时间的增量更新与失效清理，避免重复计算。语义搜索将查询文本向量化后与全库比对，返回 Top-K 相似结果；关联发现则计算所有笔记对的余弦相似度，输出超过阈值的相关链接建议。
显著优点
- 多模型支持：本地 Ollama 保障隐私，云端 OpenAI/Gemini 提供更强性能，配置灵活切换
- 增量智能：仅处理修改文件，大幅提升重复运行效率
- 阈值可调：
top_k、threshold、max_input_length等参数可精细化控制召回与精度 - 幂等安全：所有脚本可重复执行，无副作用，适合自动化集成
潜在缺点与局限
- 环境依赖：需预装 Python 3.10+、uv 包管理器及具体模型运行时，新手门槛较高
- 本地模型资源：Ollama 方案需充足 GPU/内存支撑大模型推理
- 冷启动成本：首次嵌入全库耗时较长，大库场景尤为明显
- 关联质量参差：语义相似≠知识关联，高阈值可能漏掉弱相关但有价值的连接
适合人群
- 已使用 Obsidian 构建 Zettelkasten 卡片盒笔记系统的重度用户
- 希望从关键词搜索升级至语义理解、发现笔记间隐性关联的知识管理进阶者
- 具备基础命令行与 Python 环境配置能力的技术型用户
常规风险
- API 密钥泄露：使用 OpenAI/Gemini 时需妥善管理
OPENAI_API_KEY/GOOGLE_API_KEY环境变量，避免提交至版本控制 - 隐私外泄：云端方案会将笔记内容传输至第三方，敏感资料建议强制使用本地 Ollama 模式
- 缓存一致性：直接修改笔记后若未重新运行嵌入，搜索结果可能基于过期向量
- 模型漂移：切换嵌入模型后历史缓存失效，需全量重建