尧图网页设计 
LlamaIndex ObsidianReader API 详解把 Obsidian 笔记库整体加载为带链接元数据的 RAG 文档【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexLlamaIndex 的 Obsidian 连接器llama-index-readers-obsidian提供了一个名为ObsidianReader的文档读取器用于把整个 Obsidian 笔记库vault中的 Markdown 笔记解析为 LlamaIndexDocument列表并自动为每篇笔记附加wikilinks、backlinks、可选tasks等结构化元数据。读完本篇你可以直接使用ObsidianReader将个人知识库接入VectorStoreIndex构建 RAG 问答系统并能从源码层面理解其遍历、解析、双向链接构建与安全校验的完整实现细节。安装与包结构官方示例 NoteBookObsidianReaderDemo.ipynb中的安装方式为pip install llama-index-readers-obsidian该集成包对应的模块导入路径为llama_index.readers.obsidian当前仓库中包版本为0.7.1。从其 pyproject.toml 可以看到运行环境与核心依赖Python3.10,4.0核心依赖llama-index-core0.13.0,0.15提供BaseReader与Document、llama-index-readers-file提供底层MarkdownReader、llama-index-embeddings-openai用于后续向量化嵌入的默认嵌入器。包内结构非常精简公开 API 只有一个类见 __init__.pyfrom llama_index.readers.obsidian.base import ObsidianReader __all__ [ObsidianReader]ObsidianReader 类签名与参数API 参考页 渲染的就是llama_index.readers.obsidian模块下ObsidianReader的文档字符串。核心构造函数定义为见 base.pyreader ObsidianReader( input_dirPath to Obsidian Vault, extract_tasksFalse, remove_tasks_from_textFalse, ) # 加载整个 vault返回 List[Document] documents reader.load_data()参数说明如下参数类型默认值说明input_dirstr必填Obsidian 笔记库vault的根目录路径。构造时即被转换为Path对象extract_tasksboolFalse为True时从笔记正文中提取 Markdown 任务清单项- [ ]/- [x]并存入metadata[tasks]remove_tasks_from_textboolFalse仅当extract_tasksTrue时生效为True时把任务行从文档正文中删除得到“清洗后”的正文此外ObsidianReader还继承了BaseReader的 LangChain 兼容入口# 以 LangChain Document 格式返回同一份数据 docs_lc reader.load_langchain_documents()从源码看该方法直接调用load_data()后对每个文档执行d.to_langchain_format()base.py#L139-L144因此该读取器既可加载数据进入 LlamaIndex 索引也可作为 Tool 在 LangChain Agent 中使用。每个 Document 携带的元数据模块文档字符串明确约定传入 vault 路径后解析器会把所有 Markdown 文件解析为Document列表文档会由底层MarkdownReader按 Markdown 标题header切分。每个文档都会包含以下元数据元数据键含义file_nameMarkdown 文件名folder_path文件所在文件夹的完整路径folder_name文件所在文件夹相对 vault 根目录的路径note_name笔记名不含.md扩展名也是反向链接匹配用的键wikilinks该文档中解析出的全部[[wikilink]]目标去重别名被忽略backlinks所有引用该笔记的其他笔记名列表没有则为空列表tasks仅当extract_tasksTrue时存在任务清单项字符串列表这些元数据正是把 Obsidian 作为知识图谱式数据源接入 RAG 的关键wikilinks和backlinks保留了笔记之间的双链结构folder_name/note_name可用于检索后的过滤metadata filtering。源码解析load_data 的完整执行流程ObsidianReader.load_data()的实现位于 base.py#L69-L137整体流程可以概括为“单遍遍历 两遍元数据装配”遍历 vault 目录使用os.walk(self.input_dir, followlinksFalse)递归遍历且不跟随符号链接对每个子目录先执行dirnames[:] [d for d in dirnames if not d.startswith(.)]跳过以.开头的隐藏目录例如 Obsidian 自身的.obsidian配置目录避免把配置、缓存内容混入索引。逐文件安全校验is_hardlink()通过os.stat(filepath).st_nlink 1判断文件是否为硬链接是则打印警告并跳过源码注释说明这是出于“潜在恶意利用potential malicious exploit”的考虑随后校验解析后的绝对路径必须以input_dir.resolve()为前缀防止读到 vault 之外的文件越界文件同样打印警告并跳过。正文解析对每个.md文件调用MarkdownReader().load_data(Path(filepath))。由于MarkdownReader会按标题切分一个笔记文件可能产生多个Document每段标题下为一个文档它们共享同一份文件级元数据。元数据装配为每个文档写入file_name、folder_path、folder_name用parent.relative_to(input_dir_abs)计算相对路径失败时回退为绝对路径、note_name文件名 stem。Wikilink 与 backlink 构建_extract_wikilinks()用正则\[\[([^\]])\]\]提取[[Note Name]]与[[Note Name|Alias]]两种形态遇到|时只保留别名前的目标名最后list(set(links))去重。每发现一个 wikilink就向全局字典backlinks_map结构为{目标笔记: [引用方笔记1, 引用方笔记2, ...]}中登记一条“谁引用了我”的记录。任务提取可选当extract_tasksTrue时调用_extract_tasks()其正则^\s*[-*]\s*\[\s*(?:x|X| )\s*\]\s*(.*)$re.MULTILINE匹配- [ ] 待办/* [X] 已完成这类清单行若同时remove_tasks_from_textTrue则用同一正则把任务行从正文中替换为空字符串并用清洗后的文本重建Document。回填 backlinks所有文件处理完后对每个文档执行doc.metadata[backlinks] backlinks_map.get(note_name, [])——没有笔记引用它时得到空列表。容错单个文件处理抛出异常时只打印错误并continue不会中断整个 vault 的加载。值得注意的一个实现细节是backlink 的匹配依据是 wikilink 目标名与笔记note_name文件名 stem的字符串相等而不是完整路径。从源码结构看这意味着 vault 内重名笔记不同子目录下同名.md在 backlink 归属上会产生歧义使用深层嵌套目录时需要注意这一点。端到端使用从 vault 到向量索引问答官方示例 ObsidianReaderDemo.ipynb 展示了完整的 RAG 管线。核心代码为from llama_index.readers.obsidian import ObsidianReader from llama_index.core import VectorStoreIndex # 1. 加载 vault返回 list of documents documents ObsidianReader(/Users/hursh/vault).load_data() # 2. 用文档初始化向量索引 index VectorStoreIndex.from_documents(documents) # 3. 构建查询引擎并提问 query_engine index.as_query_engine() res query_engine.query(What is the meaning of life?) print(res.response)示例中先执行%pip install llama-index-readers-obsidian与pip install llama-index并设置OPENAI_API_KEY用于默认嵌入与 LLM 调用。查询时每个文档携带的note_name、folder_name、wikilinks、backlinks等元数据会随Node一起进入索引可在检索阶段用于元数据过滤也可在响应合成时作为引用来源展示。如果只需要把笔记中的任务清单作为独立数据使用可以这样初始化reader ObsidianReader( input_dir/path/to/vault, extract_tasksTrue, # 把 - [ ] / - [x] 任务行提取到 metadata[tasks] remove_tasks_from_textTrue, # 同时把任务行从正文中移除 ) docs reader.load_data() for doc in docs: print(doc.metadata[note_name], doc.metadata.get(tasks, []))测试用例对行为的验证集成包的测试文件 test_readers_obsidian.py 覆盖了上述全部关键行为可作为 API 语义的“可执行规格”文件元数据test_file_metadata/test_file_metadata_nested验证根目录与子目录下笔记的file_name、folder_path正确嵌套笔记的folder_path应指向子目录。Wikilink 提取test_wikilink_extraction验证[[NoteOne]]与[[NoteTwo|Alias]]都只保留目标名{NoteOne, NoteTwo}test_wikilink_extraction_duplicates验证[[Note]]与[[Note|Alias]]去重后只保留一个Note。任务提取与移除test_tasks_extraction验证extract_tasksTrue且不移除时tasks中同时存在Task A、Task B且原文仍保留- [ ] Task A等任务行test_remove_tasks_from_text验证开启移除后任务行从doc.text中消失而Intro text、Conclusion text等非任务文本保留。反向链接test_single_backlink验证 A→B 场景下 B 的backlinks [A]、A 的backlinks []test_multiple_backlinks验证 A、B 均引用 C 时 C 的backlinks为{A, B}集合比较处理遍历顺序不确定性test_no_links验证无引用的笔记得到空列表。继承关系test_class断言BaseReader出现在ObsidianReader.__mro__中确认它遵循 LlamaIndex 读取器统一接口。使用注意事项与适用边界结合源码可以总结以下使用前提与限制仅加载.md文件遍历中只处理以.md结尾的文件vault 中的图片、PDF 等附件不会进入文档列表图片引用仅作为正文文本存在。不跟随符号链接、跳过隐藏目录followlinksFalse且过滤.开头目录.obsidian配置目录天然被排除依赖符号链接组织的 vault 结构不会被展开。安全过滤硬链接文件与解析后位于 vault 外部的文件会被跳过并打印警告而不是抛错。backlink 基于笔记名匹配wikilink 目标与note_name文件名去扩展名做字符串匹配不校验路径、也不做存在性检查——指向不存在笔记的 wikilink 不会出现在任何文档的backlinks中。任务格式受限任务提取只识别- [ ]/* [x]这类标准 Markdown 清单行extract_tasks默认关闭不开启时正文保持原样。文档切分粒度正文按MarkdownReader的标题切分逻辑分段一个长笔记可能对应多个Document每个分段都重复携带文件级元数据含wikilinks、backlinks。小结ObsidianReader以单一input_dir参数为入口把 Obsidian vault 转化为一份“带双链结构”的文档集合wikilinks记录笔记的出链、backlinks记录入链、folder_name/note_name提供位置与身份、可选的tasks提供待办结构。基于这些元数据你可以在 RAG 场景中实现按笔记名/目录过滤检索、顺着双链扩展上下文、或从个人笔记中批量提取任务清单等能力。相关实现集中在 base.py行为验证见 test_readers_obsidian.py端到端演示见 ObsidianReaderDemo.ipynb。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex ObsidianReader API 详解：把 Obsidian 笔记库整体加载为带链接元数据的 RAG 文档
LlamaIndex ObsidianReader API 详解把 Obsidian 笔记库整体加载为带链接元数据的 RAG 文档【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexLlamaIndex 的 Obsidian 连接器llama-index-readers-obsidian提供了一个名为ObsidianReader的文档读取器用于把整个 Obsidian 笔记库vault中的 Markdown 笔记解析为 LlamaIndexDocument列表并自动为每篇笔记附加wikilinks、backlinks、可选tasks等结构化元数据。读完本篇你可以直接使用ObsidianReader将个人知识库接入VectorStoreIndex构建 RAG 问答系统并能从源码层面理解其遍历、解析、双向链接构建与安全校验的完整实现细节。安装与包结构官方示例 NoteBookObsidianReaderDemo.ipynb中的安装方式为pip install llama-index-readers-obsidian该集成包对应的模块导入路径为llama_index.readers.obsidian当前仓库中包版本为0.7.1。从其 pyproject.toml 可以看到运行环境与核心依赖Python3.10,4.0核心依赖llama-index-core0.13.0,0.15提供BaseReader与Document、llama-index-readers-file提供底层MarkdownReader、llama-index-embeddings-openai用于后续向量化嵌入的默认嵌入器。包内结构非常精简公开 API 只有一个类见 __init__.pyfrom llama_index.readers.obsidian.base import ObsidianReader __all__ [ObsidianReader]ObsidianReader 类签名与参数API 参考页 渲染的就是llama_index.readers.obsidian模块下ObsidianReader的文档字符串。核心构造函数定义为见 base.pyreader ObsidianReader( input_dirPath to Obsidian Vault, extract_tasksFalse, remove_tasks_from_textFalse, ) # 加载整个 vault返回 List[Document] documents reader.load_data()参数说明如下参数类型默认值说明input_dirstr必填Obsidian 笔记库vault的根目录路径。构造时即被转换为Path对象extract_tasksboolFalse为True时从笔记正文中提取 Markdown 任务清单项- [ ]/- [x]并存入metadata[tasks]remove_tasks_from_textboolFalse仅当extract_tasksTrue时生效为True时把任务行从文档正文中删除得到“清洗后”的正文此外ObsidianReader还继承了BaseReader的 LangChain 兼容入口# 以 LangChain Document 格式返回同一份数据 docs_lc reader.load_langchain_documents()从源码看该方法直接调用load_data()后对每个文档执行d.to_langchain_format()base.py#L139-L144因此该读取器既可加载数据进入 LlamaIndex 索引也可作为 Tool 在 LangChain Agent 中使用。每个 Document 携带的元数据模块文档字符串明确约定传入 vault 路径后解析器会把所有 Markdown 文件解析为Document列表文档会由底层MarkdownReader按 Markdown 标题header切分。每个文档都会包含以下元数据元数据键含义file_nameMarkdown 文件名folder_path文件所在文件夹的完整路径folder_name文件所在文件夹相对 vault 根目录的路径note_name笔记名不含.md扩展名也是反向链接匹配用的键wikilinks该文档中解析出的全部[[wikilink]]目标去重别名被忽略backlinks所有引用该笔记的其他笔记名列表没有则为空列表tasks仅当extract_tasksTrue时存在任务清单项字符串列表这些元数据正是把 Obsidian 作为知识图谱式数据源接入 RAG 的关键wikilinks和backlinks保留了笔记之间的双链结构folder_name/note_name可用于检索后的过滤metadata filtering。源码解析load_data 的完整执行流程ObsidianReader.load_data()的实现位于 base.py#L69-L137整体流程可以概括为“单遍遍历 两遍元数据装配”遍历 vault 目录使用os.walk(self.input_dir, followlinksFalse)递归遍历且不跟随符号链接对每个子目录先执行dirnames[:] [d for d in dirnames if not d.startswith(.)]跳过以.开头的隐藏目录例如 Obsidian 自身的.obsidian配置目录避免把配置、缓存内容混入索引。逐文件安全校验is_hardlink()通过os.stat(filepath).st_nlink 1判断文件是否为硬链接是则打印警告并跳过源码注释说明这是出于“潜在恶意利用potential malicious exploit”的考虑随后校验解析后的绝对路径必须以input_dir.resolve()为前缀防止读到 vault 之外的文件越界文件同样打印警告并跳过。正文解析对每个.md文件调用MarkdownReader().load_data(Path(filepath))。由于MarkdownReader会按标题切分一个笔记文件可能产生多个Document每段标题下为一个文档它们共享同一份文件级元数据。元数据装配为每个文档写入file_name、folder_path、folder_name用parent.relative_to(input_dir_abs)计算相对路径失败时回退为绝对路径、note_name文件名 stem。Wikilink 与 backlink 构建_extract_wikilinks()用正则\[\[([^\]])\]\]提取[[Note Name]]与[[Note Name|Alias]]两种形态遇到|时只保留别名前的目标名最后list(set(links))去重。每发现一个 wikilink就向全局字典backlinks_map结构为{目标笔记: [引用方笔记1, 引用方笔记2, ...]}中登记一条“谁引用了我”的记录。任务提取可选当extract_tasksTrue时调用_extract_tasks()其正则^\s*[-*]\s*\[\s*(?:x|X| )\s*\]\s*(.*)$re.MULTILINE匹配- [ ] 待办/* [X] 已完成这类清单行若同时remove_tasks_from_textTrue则用同一正则把任务行从正文中替换为空字符串并用清洗后的文本重建Document。回填 backlinks所有文件处理完后对每个文档执行doc.metadata[backlinks] backlinks_map.get(note_name, [])——没有笔记引用它时得到空列表。容错单个文件处理抛出异常时只打印错误并continue不会中断整个 vault 的加载。值得注意的一个实现细节是backlink 的匹配依据是 wikilink 目标名与笔记note_name文件名 stem的字符串相等而不是完整路径。从源码结构看这意味着 vault 内重名笔记不同子目录下同名.md在 backlink 归属上会产生歧义使用深层嵌套目录时需要注意这一点。端到端使用从 vault 到向量索引问答官方示例 ObsidianReaderDemo.ipynb 展示了完整的 RAG 管线。核心代码为from llama_index.readers.obsidian import ObsidianReader from llama_index.core import VectorStoreIndex # 1. 加载 vault返回 list of documents documents ObsidianReader(/Users/hursh/vault).load_data() # 2. 用文档初始化向量索引 index VectorStoreIndex.from_documents(documents) # 3. 构建查询引擎并提问 query_engine index.as_query_engine() res query_engine.query(What is the meaning of life?) print(res.response)示例中先执行%pip install llama-index-readers-obsidian与pip install llama-index并设置OPENAI_API_KEY用于默认嵌入与 LLM 调用。查询时每个文档携带的note_name、folder_name、wikilinks、backlinks等元数据会随Node一起进入索引可在检索阶段用于元数据过滤也可在响应合成时作为引用来源展示。如果只需要把笔记中的任务清单作为独立数据使用可以这样初始化reader ObsidianReader( input_dir/path/to/vault, extract_tasksTrue, # 把 - [ ] / - [x] 任务行提取到 metadata[tasks] remove_tasks_from_textTrue, # 同时把任务行从正文中移除 ) docs reader.load_data() for doc in docs: print(doc.metadata[note_name], doc.metadata.get(tasks, []))测试用例对行为的验证集成包的测试文件 test_readers_obsidian.py 覆盖了上述全部关键行为可作为 API 语义的“可执行规格”文件元数据test_file_metadata/test_file_metadata_nested验证根目录与子目录下笔记的file_name、folder_path正确嵌套笔记的folder_path应指向子目录。Wikilink 提取test_wikilink_extraction验证[[NoteOne]]与[[NoteTwo|Alias]]都只保留目标名{NoteOne, NoteTwo}test_wikilink_extraction_duplicates验证[[Note]]与[[Note|Alias]]去重后只保留一个Note。任务提取与移除test_tasks_extraction验证extract_tasksTrue且不移除时tasks中同时存在Task A、Task B且原文仍保留- [ ] Task A等任务行test_remove_tasks_from_text验证开启移除后任务行从doc.text中消失而Intro text、Conclusion text等非任务文本保留。反向链接test_single_backlink验证 A→B 场景下 B 的backlinks [A]、A 的backlinks []test_multiple_backlinks验证 A、B 均引用 C 时 C 的backlinks为{A, B}集合比较处理遍历顺序不确定性test_no_links验证无引用的笔记得到空列表。继承关系test_class断言BaseReader出现在ObsidianReader.__mro__中确认它遵循 LlamaIndex 读取器统一接口。使用注意事项与适用边界结合源码可以总结以下使用前提与限制仅加载.md文件遍历中只处理以.md结尾的文件vault 中的图片、PDF 等附件不会进入文档列表图片引用仅作为正文文本存在。不跟随符号链接、跳过隐藏目录followlinksFalse且过滤.开头目录.obsidian配置目录天然被排除依赖符号链接组织的 vault 结构不会被展开。安全过滤硬链接文件与解析后位于 vault 外部的文件会被跳过并打印警告而不是抛错。backlink 基于笔记名匹配wikilink 目标与note_name文件名去扩展名做字符串匹配不校验路径、也不做存在性检查——指向不存在笔记的 wikilink 不会出现在任何文档的backlinks中。任务格式受限任务提取只识别- [ ]/* [x]这类标准 Markdown 清单行extract_tasks默认关闭不开启时正文保持原样。文档切分粒度正文按MarkdownReader的标题切分逻辑分段一个长笔记可能对应多个Document每个分段都重复携带文件级元数据含wikilinks、backlinks。小结ObsidianReader以单一input_dir参数为入口把 Obsidian vault 转化为一份“带双链结构”的文档集合wikilinks记录笔记的出链、backlinks记录入链、folder_name/note_name提供位置与身份、可选的tasks提供待办结构。基于这些元数据你可以在 RAG 场景中实现按笔记名/目录过滤检索、顺着双链扩展上下文、或从个人笔记中批量提取任务清单等能力。相关实现集中在 base.py行为验证见 test_readers_obsidian.py端到端演示见 ObsidianReaderDemo.ipynb。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考