LlamaIndex 集成指南PsychicReader 如何通过通用 API 加载多 SaaS 数据源【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexPsychicReader 是 LlamaIndex 官方集成包llama-index-readers-psychic提供的文档加载器用于对接 Psychic 这一通过一个通用 API 同步多个 SaaS 应用数据的平台。本文以当前仓库中 readers/psychic API 参考页 指定的llama_index.readers.psychic模块为对象结合其源码、README 与测试完整讲解从安装、鉴权、加载数据到源码级参数校验的实操方案。读完本文你将能够独立完成 Psychic 连接器的配置、数据拉取并将其接入 LlamaIndex 索引构建与 Agent 工具链路。PsychicReader 的定位与适用场景Psychic 是一个面向 SaaS 数据同步的平台其核心价值在于开发者无需为 Notion、Confluence、Google Drive 等每一个 SaaS 应用单独实现 OAuth 与数据拉取逻辑而是通过 Psychic 提供的通用 API统一完成连接与取数。PsychicReader 就是这个通用 API 在 LlamaIndex 生态中的适配层。从源码 docstring 可以看到它的明确职责描述见 base.pyPsychic is a platform that allows syncing data from many SaaS apps through one universal API. This reader connects to an instance of Psychic and reads data from it, given a connector ID, account ID, and API key.即给定 connector ID连接器标识、account ID账户标识和 API keyPsychicReader 就能从 Psychic 实例中读取该账户在对应 SaaS 应用里已同步的数据。包级 README见 README.md进一步说明该加载器既可直接用于把数据载入 LlamaIndex也可进一步作为 Agent 的 Tool 使用。典型适用场景包括多租户 SaaS 数据汇聚、跨应用文档检索RAG、以及需要在统一数据管道中消费多个外部知识源的场景。安装与依赖环境PsychicReader 以独立集成包形式发布通过 pip 安装即可pip install llama-index-readers-psychic从该包 pyproject.toml 可以确认其运行时依赖与版本约束依赖项版本约束作用psychicapi0.8.4,0.9Psychic 官方 Python SDK提供Psychic客户端与ConnectorId枚举llama-index-core0.13.0,0.15LlamaIndex 核心库提供BaseReader基类与Document数据模型同时包要求 Python 版本3.10,4.0。安装时 pip 会自动解析上述依赖如果代码运行时提示psychicapi缺失源码 base.py 中的ImportError分支会明确提示执行pip install psychicapi。快速上手最小可用示例包级 README 给出了可直接复制的完整用法见 README.mdfrom llama_index.readers.psychic import PsychicReader # 初始化 PsychicReader reader PsychicReader(psychic_keyPsychic Secret Key) # 从 Psychic 加载数据 documents reader.load_data( connector_idConnector ID, account_idAccount ID )其中psychic_keyPsychic 平台的 Secret Key可在 Psychic 控制台的 API Keys 页面获取connector_id目标 SaaS 应用的连接器 ID如 Notion、Confluence 等account_id需要读取数据的账户 ID用于在多账户场景下定位具体数据归属。load_data返回的是List[Document]即 LlamaIndex 核心数据模型Document的列表可以直接用于构建索引例如from llama_index.core import VectorStoreIndex index VectorStoreIndex.from_documents(documents) query_engine index.as_query_engine()也可以把加载到的文档进一步封装为工具接入 Agent 工作流实现连接 SaaS 数据 → 检索 → 问答/Agent 决策的完整链路。认证方式参数与环境变量PsychicReader 的鉴权设计兼顾了显式传参与生产环境安全两种诉求。查看 base.py 的构造函数实现def __init__(self, psychic_key: Optional[str] None) - None: try: from psychicapi import ConnectorId, Psychic except ImportError: raise ImportError( psychicapi package not found, please run pip install psychicapi ) if psychic_key is None: psychic_key os.environ[PSYCHIC_SECRET_KEY] if psychic_key is None: raise ValueError( Must specify psychic_key or set environment variable PSYCHIC_SECRET_KEY. ) self.psychic Psychic(secret_keypsychic_key) self.ConnectorId ConnectorId两种认证方式的优先级如下显式传参构造时传入psychic_key...环境变量兜底不传psychic_key时自动读取PSYCHIC_SECRET_KEY环境变量。如果两者都缺失构造函数会抛出ValueError并给出明确提示。这种设计使密钥不必硬编码进代码或 Notebook适合在 CI/CD 或容器环境中通过环境变量注入密钥。构造成功后SDK 客户端Psychic(secret_keypsychic_key)被保存在self.psychicConnectorId枚举也被缓存为实例属性供后续load_data做连接器校验。源码级解析load_data 的完整数据流load_data是 PsychicReader 的核心方法见 base.pydef load_data( self, connector_id: Optional[str] None, account_id: Optional[str] None ) - List[Document]: if not connector_id or not account_id: raise ValueError(Must specify both connector_id and account_id.) if connector_id not in self.ConnectorId.__members__: raise ValueError(Invalid connector ID.) # get all the documents in the database docs [] data self.psychic.get_documents(self.ConnectorId[connector_id], account_id) for resource in data: text resource.get(content) doc_id resource.get(uri) docs.append( Document( texttext, id_doc_id, metadata{connector_id: connector_id, account_id: account_id}, ) ) return docs其数据流可以拆解为四个阶段阶段 1必填参数校验。connector_id与account_id必须同时提供任一缺失都会抛出ValueError(Must specify both connector_id and account_id.)。这是最容易被忽略的坑——两个参数是成对出现的缺一不可。阶段 2连接器合法性校验。connector_id必须是psychicapi.ConnectorId枚举的成员通过self.ConnectorId.__members__判断否则抛出ValueError(Invalid connector ID.)。从源码结构看ConnectorId是 SDK 内置的枚举类型枚举成员对应 Psychic 支持的各个 SaaS 应用这意味着连接器 ID 不能随意传字符串必须是平台支持的合法标识。阶段 3拉取文档。调用self.psychic.get_documents(self.ConnectorId[connector_id], account_id)获取指定账户下的全部文档数据。返回的data是可迭代的资源列表每个资源包含content正文文本与uri文档唯一标识等字段。阶段 4映射为 LlamaIndex Document。遍历每个资源构造核心数据模型Document( texttext, # 资源正文 id_doc_id, # 资源 uri 作为文档 ID metadata{connector_id: connector_id, account_id: account_id}, )这里有三点值得注意文档 ID 语义化以 SaaS 侧的uri作为Document.id_使文档 ID 在 LlamaIndex 与源系统之间保持可追溯便于去重与增量更新元数据自动打标每个 Document 的metadata都固化写入connector_id与account_id在多连接器、多账户的混合索引中可以直接基于元数据做过滤检索统一文本格式content字段被标准化为Document.text后续无需额外转换即可进入文本切分、向量化等管道。参数速查表参数位置必填说明校验规则psychic_keyPsychicReader.__init__否二选一Psychic Secret Key在 Psychic 控制台 API Keys 页面获取缺省时读取PSYCHIC_SECRET_KEY环境变量两者皆无则抛ValueErrorconnector_idload_data是目标 SaaS 应用的连接器 ID必须同时提供account_id且必须是ConnectorId枚举成员否则抛ValueErroraccount_idload_data是数据归属账户 ID多账户场景下区分数据来源必须与connector_id成对提供返回值List[Document]中的每个元素均携带text、id_与metadata内含connector_id、account_id。在 LlamaIndex 中的完整接入示例将以上要素组合起来一个可运行的端到端示例认证走环境变量密钥不入库export PSYCHIC_SECRET_KEYyour-secret-keyfrom llama_index.core import VectorStoreIndex from llama_index.readers.psychic import PsychicReader # 1. 初始化加载器自动读取 PSYCHIC_SECRET_KEY reader PsychicReader() # 2. 拉取指定连接器与账户下的全部文档 documents reader.load_data( connector_idnotion, account_idteam-a ) # 3. 构建向量索引 index VectorStoreIndex.from_documents(documents) # 4. 查询 response index.as_query_engine().query(What are the key action items?) print(response)若需要做元数据过滤例如只检索某个账户的数据可以利用load_data已写入的metadatafrom llama_index.core.retrievers import VectorIndexRetriever from llama_index.core.query_engine import RetrieverQueryEngine retriever VectorIndexRetriever( indexindex, filtersMetadataFilters( filters[ MetadataFilter(keyaccount_id, valueteam-a), ] ), ) query_engine RetrieverQueryEngine.from_args(retrieverretriever)工程规范与测试验证该集成包遵循 LlamaIndex 集成生态的统一工程规范可以从仓库中得到验证导入路径与导出面模块入口init.py 从base.py导出PsychicReader并声明__all__ [PsychicReader]与 API 参考页中members: - PsychicReader的声明一致继承体系PsychicReader继承自llama_index.core.readers.base.BaseReader符合 LlamaIndex 对 Reader 的标准抽象见 base.py测试用例test_readers_psychic.py 通过检查PsychicReader.__mro__断言其基类链中包含BaseReader验证了类型契约的成立代码质量配置pyproject.toml 中启用了mypydisallow_untyped_defs true、ruff、pylint、codespell等工具构建后端为 hatchling包名元数据llama-index-readers-psychic与安装名一致。这些细节说明PsychicReader 不是孤立脚本而是 LlamaIndex 官方 Reader 生态中经过类型检查、测试与打包规范约束的标准组件。使用注意事项密钥管理优先使用PSYCHIC_SECRET_KEY环境变量而非硬编码密钥两者皆缺省时构造函数直接报错属于快速失败设计参数成对connector_id与account_id必须同时传入单独传参不会进入拉取逻辑连接器合法性连接器 ID 必须属于ConnectorId枚举传入平台不支持的字符串会在调用 SDK 之前被拦截一次性全量拉取get_documents一次性返回账户下的全部文档数据量较大时建议配合 LlamaIndex 的文档处理管道切分、去重控制后续开销版本配套该包依赖llama-index-core 0.13.0,0.15使用前应确保核心库版本落在该区间避免接口不兼容。以上内容均基于当前仓库中 PsychicReader 源码、包级 README、单元测试 与 pyproject.toml 归纳而成可作为接入 Psychic 数据源到 LlamaIndex 检索链路的直接参考。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考