DataHub Notion 数据源接入实战将 Notion 工作区文档摄取为可语义搜索的 Document 实体【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubDataHub 的 Notion 数据源source.type: notion用于将 Notion 工作区中的页面Pages与数据库Databases摄取为 DataHub 的 Document 实体并保留页面间的父子层级关系可选地为文档内容生成语义向量嵌入Semantic Embedding以支持自然语言语义搜索。本文以官方 Notion 数据源文档为主体结合仓库中的配置模型、摄取实现与示例 Recipe完整讲解前置准备、配置参数、运行场景、状态化增量摄取、性能调优与故障排查帮助你从零开始将团队文档知识接入 DataHub 的统一元数据平台。概述Notion 数据源能做什么Notion 是一个文档与协作平台DataHub 为其提供了专门的摄取连接器覆盖以下能力对应官方源文档与notion_pre.md文档/工作区实体与层级上下文把 Notion 页面和数据库作为知识类资产Document 实体摄取保留页面间的父子关系与浏览路径内容提取从 Notion 页面提取全文支持全部常见块类型数据库中的每一行作为一个独立文档摄入可选语义嵌入为文档生成向量嵌入开启 DataHub 的语义搜索能力状态化删除检测Stateful Deletion Detection自动清理在 Notion 中已删除的陈旧实体。从源码装饰器看该连接器当前标记为ALPHA支持状态核心实现位于 notion_source.pyplatform_name(Notion)、config_class(NotionSourceConfig)。注意该数据源不支持 DataHub Cloud 的 Remote Executor 运行方式必须使用自托管self-hosted摄取环境运行这是官方文档明确标注的限制。概念映射Notion 资产如何对应 DataHub 概念官方文档指出虽然针对 Notion 的专属概念映射仍在完善中但以下表格展示了 DataHub 中的通用概念映射方式用于理解摄取后的资产组织形态源概念Source ConceptDataHub 概念说明平台 / 账户 / 项目作用域Platform Instance、Container在平台上下文中组织资产核心技术资产如表 / 视图 / 主题 / 文件Dataset主要摄取的技术资产Schema 字段 / 列SchemaField在支持 Schema 提取时包含所有权与协作主体CorpUser、CorpGroup由支持所有权与身份元数据的模块产出依赖与处理关系Lineage edges在支持且启用血缘提取时可用前置准备1. 创建 Notion 内部集成Integration打开 Notion 的「我的集成」my-integrations管理页面点击 New integration为集成命名如 DataHub Integration选择目标工作区复制生成的Internal Integration Token以secret_开头后续作为api_key使用。在源码中api_key是必填项notion_config.py并通过validate_api_key校验器强制非空。建议集成开启Read content读取内容能力Read comments 为可选项用于提取评论元数据。2. 将页面共享给集成Notion 集成只能访问显式共享给它的页面在 Notion 中打开目标页面或数据库点击右上角Share或 ... 菜单中的 Add connections/Connect to搜索你的集成名称并点击Invite。关键提示若希望递归摄取只需共享顶层页面即可——子页面会自动继承访问权限。3. 准备嵌入 Provider可选如果需要语义搜索能力任选其一Cohere注册并创建 API Key支持embed-english-v3.0、embed-multilingual-v3.0等模型AWS Bedrock需要具备 Bedrock 访问权限的 AWS 账户在 AWS 控制台启用 Cohere 模型Bedrock → Model access并授予bedrock:InvokeModelIAM 权限推荐区域us-west-2。服务端完整的语义搜索配置请参考语义搜索配置文档它同时覆盖了 OpenAI、AWS Bedrock、Cohere 三种 Provider 的 Helm 与环境变量两种配置方式。配置详解核心参数与默认值Notion 数据源的配置模型定义在 notion_config.py继承自StatefulIngestionConfigBase与ConfigModel。下面按「Notion 专有字段」与「共享配置节」两部分讲解。Notion 专有字段顶层参数默认值说明api_key必填Notion 内部集成 Tokensecret_开头不可为空page_ids[]要摄取的页面 ID 列表支持裸 ID 或完整 URL若与database_ids同时为空将自动发现并摄取集成可访问的全部页面与数据库database_ids[]要摄取的数据库 ID 列表规则同上recursivetrue是否递归抓取子页面为true时摄取指定页面/数据库的所有后代页面document_import_modeEXTERNALNATIVE在 DataHub 中导入可编辑文档EXTERNAL导入链接回 Notion 的只读引用parent_document_urnNone可选顶层导入页面的父 Document URNmax_documents10000单次摄取最大文档数达到上限后任务停止并报错设为0或-1可禁用限制ID 校验与规范化源码级page_ids/database_ids的校验器validate_page_ids/validate_database_ids非常实用——它们同时支持两种输入裸 ID32 位十六进制字符可带或不带连字符完整 URL自动从https://www.notion.so/Page-Title-{PAGE_ID}或https://www.notion.so/{DATABASE_ID}?v...中提取 ID去掉查询参数与锚点取最后一个路径段中最后一个-之后的内容并校验为 32 位合法十六进制串。无论哪种输入最终都会规范化为 Notion 标准格式8-4-4-4-12如2bffc6a6-4277-8024-97c9-d0f26faa4480。若格式非法会直接抛出校验错误帮助你尽早发现问题。共享配置节这些配置节与 unstructured 系列数据源共享定义于metadata-ingestion/src/datahub/ingestion/source/unstructured/下processing文本提取与分区配置partition.strategy可选auto/fast/ocr_only/hi_respartition_by_api是否调用 Unstructured APIparallelism并行度document_mappingDocument 实体映射ID 生成模式、标题提取、来源 URL/ID 是否写入等hierarchy父子关系配置enabled默认truefiltering文档过滤skip_empty_documents默认true、min_text_length默认 50datahubDataHub 连接配置用于查询服务端嵌入配置chunking分块策略by_title/basicembedding嵌入生成配置Bedrock、Cohere、OpenAI、Vertex AI 等 Provideradvanced高级选项工作目录、错误处理。源码中有三个值得注意的自动默认值覆盖逻辑model_validator层级策略自动切换当hierarchy.enabled且父策略为默认的folder时自动改写为notion使用 Notion 原生层级导入模式联动document_mapping.source.type会被自动设为document_import_mode的取值若配置了parent_document_urn它也会成为层级映射的根父节点稳定的 Document URN默认 ID 模式{source_type}-{directory}-{basename}被改写为{source_type}-{basename}避免把本地缓存目录路径写进 URN从而生成稳定、可移植的 URN例如urn:li:document:notion-2bffc6a6-4277-8024-97c9-d0f26faa4480。最小可运行 Recipe官方提供了开箱即用的示例配置notion_recipe.yml 与 notion_to_datahub.ymlsource: type: notion config: # Notion 集成 Token必填 api_key: ${NOTION_API_KEY} # 指定要摄取的页面ID 可从页面 URL 获取 page_ids: - your-page-id-here # 或者摄取集成可访问的全部内容page_ids 与 database_ids 都留空 # page_ids: [] # database_ids: [] sink: type: datahub-rest config: server: http://localhost:8080安装与运行方式来自示例 Recipe 注释# 安装带 notion 依赖的 DataHub 摄取器 pip install acryl-datahub[notion] # 运行摄取 datahub ingest -c notion_to_datahub.yml关于最小配置的说明当page_ids与database_ids均为空时源会自动发现并摄取集成可访问的全部页面与数据库同时默认开启层级模式、按需使用服务端嵌入配置——也就是说只需提供api_key即可完成一次完整的全工作区摄取。典型使用场景场景一全工作区文档语义搜索以工作区根页面为起点开启递归与 Cohere 嵌入source: type: notion config: api_key: ${NOTION_API_KEY} # 从工作区根页面开始 page_ids: - workspace_root_page_id recursive: true # 开启语义嵌入 embedding: provider: cohere model: embed-english-v3.0 api_key: ${COHERE_API_KEY}场景二只摄取指定数据库例如只摄取 Product Requirements 数据库且不递归子页面source: type: notion config: api_key: ${NOTION_API_KEY} # 只摄取该数据库 database_ids: - product_requirements_db_id recursive: false # 只取数据库条目不取子页面场景三多工作区摄取多工作区需要多个集成每个集成对应一个 Token但可以在同一个 Recipe 中配置多个根页面source: type: notion config: api_key: ${NOTION_API_KEY} # 来自不同工作区的多个根页面 page_ids: - workspace_1_page_id - workspace_2_page_id recursive: true场景四基于 AWS Bedrock 的生产级配置使用 IAM 角色认证无需 API Key并开启状态化摄取做增量更新source: type: notion config: api_key: ${NOTION_API_KEY} page_ids: - company_wiki_root recursive: true # 使用 AWS Bedrock无需 API Key走 IAM 角色 embedding: provider: bedrock aws_region: us-west-2 model: cohere.embed-english-v3 # 开启状态化摄取实现增量更新 stateful_ingestion: enabled: true工作原理处理流水线与源码实现官方文档描述了六步处理流水线Discovery通过 Notion API 发现页面/数据库Download由 Unstructured.io 下载并将内容转换为结构化格式Extraction从 Notion 页面提取文本、元数据与层级Chunking开启嵌入时将文档切分为语义块Embedding为每个块生成向量嵌入开启时Emission将携带SemanticContent方面的 Document 实体写入 DataHub。层级关系如何构建源码级层级提取逻辑位于 notion_hierarchy.py。由于 Notion API 只返回每个页面的直接父级additional_metadata.parent中可能为page_id、database_id或workspace三种类型不像 Confluence 那样返回完整祖先数组因此连接器需要extract_parent_id()解析单页的直接父 IDworkspace类型视为根节点无父级extract_ancestor_chain()沿着父链接向上遍历、重建完整祖先链并做环检测遇到已访问节点立即停止防止循环引用build_browse_path_v2()把祖先链转换为BrowsePathsV2方面为 DataHub UI 提供层级浏览路径当通过page_ids/database_ids限定摄取范围时这些 ID 会作为浏览路径锚点祖先链不会越过锚点向上延伸。这意味着只要hierarchy.enabled: true默认且父页面也在此次摄取范围内你就能在 DataHub 中按照 Notion 原始结构逐级浏览文档。对 Notion API 变更的兼容处理从 notion_source.py 可以看到连接器针对底层unstructured-ingest0.7.2 与 Notion API 的版本差异内置了多组 monkeypatch例如过滤 Page 类不认识的is_locked新字段为 20 余个数据库属性类过滤description字段在数据库 HTML 输出中补上数据库标题避免文档标题变成通用 ID绕过DatabasesEndpoint.super().query()的兼容性问题优雅处理 Synced Block、编号列表新字段、未知图标类型以及对全部FromJSONMixin类型类做通用未知字段过滤。这些补丁的共性设计是降级而非失败遇到新字段时丢弃该字段并记录一次性告警保证整批摄取不被中断——这是理解该源对 Notion API 频繁演进的健壮性设计的关键。状态化摄取内容哈希驱动的增量更新状态化摄取是本源的核心能力之一其工作机制为基于内容哈希的变化检测对应notion_source.py中的_initialize_state_tracking与文档状态跟踪计算「文档内容 嵌入配置」的 SHA-256 哈希与上一次运行保存的哈希比对检测变化仅当哈希变化时才重新处理该文档跟踪所有已产出 URN用于删除检测。实际运行效果首次运行处理全部文档后续运行只处理新增/变更的文档未变化的文档直接跳过页面被删除自动在 DataHub 中软删除对应实体。同时它继承自StatefulIngestionSourceBase支持stateful_ingestion.enabled: true的显式开启部分场景下为默认行为删除检测由StatefulStaleMetadataRemovalConfig支撑。摄取报告类 notion_report.py 会统计扫描/处理/跳过/失败的文件数、创建的文档数含文件夹文档、提取文本字节数、嵌入成功/失败数、跳过的 Synced Block 等指标便于在datahub ingest输出中定位问题。性能调优并行度设置processing: parallelism: num_processes: 4 # 提高以加速处理默认: 2 max_connections: 20 # 并发 API 连接数默认: 10官方建议小型工作区100 页num_processes: 2中型工作区100–1000 页num_processes: 4大型工作区1000 页num_processes: 8过滤配置filtering: min_text_length: 100 # 跳过过短页面默认: 50 skip_empty_documents: true # 跳过空页面默认: true分块优化chunking: strategy: by_title # 保留文档结构推荐 max_characters: 500 # 分块大小默认: 500 combine_text_under_n_chars: 100 # 合并小分块默认: 100限制与注意事项Notion API 限制速率限制付费工作区约 3 请求/秒免费工作区约 1 请求/秒访问范围集成只能看到显式共享的页面内容类型部分块可能无法完美提取如复杂嵌入、Synced Block——源码会跳过其内容并记录告警。性能考量大型工作区首次运行耗时较长嵌入生成会增加与内容量成正比的处理时间Unstructured API 与嵌入 Provider 可能产生费用。内容提取能力边界支持文本、标题、列表、代码块、表格、Callout、Toggle、引用等块类型有限支持嵌入、公式、文件提取为链接/引用不支持实时图表、看板/画廊/时间线等数据库视图。故障排查速查表Integration not found 或 Unauthorized 错误检查api_key是否正确应以secret_开头确认页面已共享给集成确认集成拥有 Read content 能力。内容为空或缺失确认页面包含文本skip_empty_documents: true默认会跳过空页面检查min_text_length过滤设置默认 50 字符期望子页面时确认recursive: true检查子页面未被单独限制访问。摄取缓慢提高processing.parallelism.num_processes默认 2本地处理可考虑partition_by_api: false代价是占用更多内存用page_ids限定范围避免摄取整个工作区首次运行必然较慢后续运行走增量更新。嵌入生成失败检查 Provider 的 API Key留意 Provider 自身的速率限制如 Cohere 约 10k 请求/分钟确认嵌入模型名对应当前 ProviderBedrock 场景确认 IAM 权限与 AWS 控制台已启用模型访问。状态化摄取不生效确认配置了stateful_ingestion.enabled: true检查 DataHub 连接源需要查询上一次运行的状态若使用文件状态确认状态文件路径可写在摄取输出中查找状态持久化日志。层级/父子关系缺失确认hierarchy.enabled: true默认开启检查父页面是否也被摄取确认recursive: true父页面必须对集成可访问。如果摄取失败请先验证凭据、权限、连通性与范围过滤再结合摄取日志中的源特定错误信息逐项调整配置。总结DataHub 的 Notion 数据源用一条 YAML Recipe 就能把整个工作区的文档资产接入统一元数据平台页面与数据库映射为 Document 实体、层级结构转换为可浏览路径、内容哈希驱动增量更新、可选嵌入开启语义搜索。其健壮性设计ID 规范化、未知字段降级、层级环检测让它在 Notion API 频繁演进的环境中依然稳定可用。相关参考材料官方源文档 README.md、前置说明、后置说明、完整示例 notion_to_datahub.yml以及服务端语义搜索配置。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub Notion 数据源接入实战：将 Notion 工作区文档摄取为可语义搜索的 Document 实体
DataHub Notion 数据源接入实战将 Notion 工作区文档摄取为可语义搜索的 Document 实体【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubDataHub 的 Notion 数据源source.type: notion用于将 Notion 工作区中的页面Pages与数据库Databases摄取为 DataHub 的 Document 实体并保留页面间的父子层级关系可选地为文档内容生成语义向量嵌入Semantic Embedding以支持自然语言语义搜索。本文以官方 Notion 数据源文档为主体结合仓库中的配置模型、摄取实现与示例 Recipe完整讲解前置准备、配置参数、运行场景、状态化增量摄取、性能调优与故障排查帮助你从零开始将团队文档知识接入 DataHub 的统一元数据平台。概述Notion 数据源能做什么Notion 是一个文档与协作平台DataHub 为其提供了专门的摄取连接器覆盖以下能力对应官方源文档与notion_pre.md文档/工作区实体与层级上下文把 Notion 页面和数据库作为知识类资产Document 实体摄取保留页面间的父子关系与浏览路径内容提取从 Notion 页面提取全文支持全部常见块类型数据库中的每一行作为一个独立文档摄入可选语义嵌入为文档生成向量嵌入开启 DataHub 的语义搜索能力状态化删除检测Stateful Deletion Detection自动清理在 Notion 中已删除的陈旧实体。从源码装饰器看该连接器当前标记为ALPHA支持状态核心实现位于 notion_source.pyplatform_name(Notion)、config_class(NotionSourceConfig)。注意该数据源不支持 DataHub Cloud 的 Remote Executor 运行方式必须使用自托管self-hosted摄取环境运行这是官方文档明确标注的限制。概念映射Notion 资产如何对应 DataHub 概念官方文档指出虽然针对 Notion 的专属概念映射仍在完善中但以下表格展示了 DataHub 中的通用概念映射方式用于理解摄取后的资产组织形态源概念Source ConceptDataHub 概念说明平台 / 账户 / 项目作用域Platform Instance、Container在平台上下文中组织资产核心技术资产如表 / 视图 / 主题 / 文件Dataset主要摄取的技术资产Schema 字段 / 列SchemaField在支持 Schema 提取时包含所有权与协作主体CorpUser、CorpGroup由支持所有权与身份元数据的模块产出依赖与处理关系Lineage edges在支持且启用血缘提取时可用前置准备1. 创建 Notion 内部集成Integration打开 Notion 的「我的集成」my-integrations管理页面点击 New integration为集成命名如 DataHub Integration选择目标工作区复制生成的Internal Integration Token以secret_开头后续作为api_key使用。在源码中api_key是必填项notion_config.py并通过validate_api_key校验器强制非空。建议集成开启Read content读取内容能力Read comments 为可选项用于提取评论元数据。2. 将页面共享给集成Notion 集成只能访问显式共享给它的页面在 Notion 中打开目标页面或数据库点击右上角Share或 ... 菜单中的 Add connections/Connect to搜索你的集成名称并点击Invite。关键提示若希望递归摄取只需共享顶层页面即可——子页面会自动继承访问权限。3. 准备嵌入 Provider可选如果需要语义搜索能力任选其一Cohere注册并创建 API Key支持embed-english-v3.0、embed-multilingual-v3.0等模型AWS Bedrock需要具备 Bedrock 访问权限的 AWS 账户在 AWS 控制台启用 Cohere 模型Bedrock → Model access并授予bedrock:InvokeModelIAM 权限推荐区域us-west-2。服务端完整的语义搜索配置请参考语义搜索配置文档它同时覆盖了 OpenAI、AWS Bedrock、Cohere 三种 Provider 的 Helm 与环境变量两种配置方式。配置详解核心参数与默认值Notion 数据源的配置模型定义在 notion_config.py继承自StatefulIngestionConfigBase与ConfigModel。下面按「Notion 专有字段」与「共享配置节」两部分讲解。Notion 专有字段顶层参数默认值说明api_key必填Notion 内部集成 Tokensecret_开头不可为空page_ids[]要摄取的页面 ID 列表支持裸 ID 或完整 URL若与database_ids同时为空将自动发现并摄取集成可访问的全部页面与数据库database_ids[]要摄取的数据库 ID 列表规则同上recursivetrue是否递归抓取子页面为true时摄取指定页面/数据库的所有后代页面document_import_modeEXTERNALNATIVE在 DataHub 中导入可编辑文档EXTERNAL导入链接回 Notion 的只读引用parent_document_urnNone可选顶层导入页面的父 Document URNmax_documents10000单次摄取最大文档数达到上限后任务停止并报错设为0或-1可禁用限制ID 校验与规范化源码级page_ids/database_ids的校验器validate_page_ids/validate_database_ids非常实用——它们同时支持两种输入裸 ID32 位十六进制字符可带或不带连字符完整 URL自动从https://www.notion.so/Page-Title-{PAGE_ID}或https://www.notion.so/{DATABASE_ID}?v...中提取 ID去掉查询参数与锚点取最后一个路径段中最后一个-之后的内容并校验为 32 位合法十六进制串。无论哪种输入最终都会规范化为 Notion 标准格式8-4-4-4-12如2bffc6a6-4277-8024-97c9-d0f26faa4480。若格式非法会直接抛出校验错误帮助你尽早发现问题。共享配置节这些配置节与 unstructured 系列数据源共享定义于metadata-ingestion/src/datahub/ingestion/source/unstructured/下processing文本提取与分区配置partition.strategy可选auto/fast/ocr_only/hi_respartition_by_api是否调用 Unstructured APIparallelism并行度document_mappingDocument 实体映射ID 生成模式、标题提取、来源 URL/ID 是否写入等hierarchy父子关系配置enabled默认truefiltering文档过滤skip_empty_documents默认true、min_text_length默认 50datahubDataHub 连接配置用于查询服务端嵌入配置chunking分块策略by_title/basicembedding嵌入生成配置Bedrock、Cohere、OpenAI、Vertex AI 等 Provideradvanced高级选项工作目录、错误处理。源码中有三个值得注意的自动默认值覆盖逻辑model_validator层级策略自动切换当hierarchy.enabled且父策略为默认的folder时自动改写为notion使用 Notion 原生层级导入模式联动document_mapping.source.type会被自动设为document_import_mode的取值若配置了parent_document_urn它也会成为层级映射的根父节点稳定的 Document URN默认 ID 模式{source_type}-{directory}-{basename}被改写为{source_type}-{basename}避免把本地缓存目录路径写进 URN从而生成稳定、可移植的 URN例如urn:li:document:notion-2bffc6a6-4277-8024-97c9-d0f26faa4480。最小可运行 Recipe官方提供了开箱即用的示例配置notion_recipe.yml 与 notion_to_datahub.ymlsource: type: notion config: # Notion 集成 Token必填 api_key: ${NOTION_API_KEY} # 指定要摄取的页面ID 可从页面 URL 获取 page_ids: - your-page-id-here # 或者摄取集成可访问的全部内容page_ids 与 database_ids 都留空 # page_ids: [] # database_ids: [] sink: type: datahub-rest config: server: http://localhost:8080安装与运行方式来自示例 Recipe 注释# 安装带 notion 依赖的 DataHub 摄取器 pip install acryl-datahub[notion] # 运行摄取 datahub ingest -c notion_to_datahub.yml关于最小配置的说明当page_ids与database_ids均为空时源会自动发现并摄取集成可访问的全部页面与数据库同时默认开启层级模式、按需使用服务端嵌入配置——也就是说只需提供api_key即可完成一次完整的全工作区摄取。典型使用场景场景一全工作区文档语义搜索以工作区根页面为起点开启递归与 Cohere 嵌入source: type: notion config: api_key: ${NOTION_API_KEY} # 从工作区根页面开始 page_ids: - workspace_root_page_id recursive: true # 开启语义嵌入 embedding: provider: cohere model: embed-english-v3.0 api_key: ${COHERE_API_KEY}场景二只摄取指定数据库例如只摄取 Product Requirements 数据库且不递归子页面source: type: notion config: api_key: ${NOTION_API_KEY} # 只摄取该数据库 database_ids: - product_requirements_db_id recursive: false # 只取数据库条目不取子页面场景三多工作区摄取多工作区需要多个集成每个集成对应一个 Token但可以在同一个 Recipe 中配置多个根页面source: type: notion config: api_key: ${NOTION_API_KEY} # 来自不同工作区的多个根页面 page_ids: - workspace_1_page_id - workspace_2_page_id recursive: true场景四基于 AWS Bedrock 的生产级配置使用 IAM 角色认证无需 API Key并开启状态化摄取做增量更新source: type: notion config: api_key: ${NOTION_API_KEY} page_ids: - company_wiki_root recursive: true # 使用 AWS Bedrock无需 API Key走 IAM 角色 embedding: provider: bedrock aws_region: us-west-2 model: cohere.embed-english-v3 # 开启状态化摄取实现增量更新 stateful_ingestion: enabled: true工作原理处理流水线与源码实现官方文档描述了六步处理流水线Discovery通过 Notion API 发现页面/数据库Download由 Unstructured.io 下载并将内容转换为结构化格式Extraction从 Notion 页面提取文本、元数据与层级Chunking开启嵌入时将文档切分为语义块Embedding为每个块生成向量嵌入开启时Emission将携带SemanticContent方面的 Document 实体写入 DataHub。层级关系如何构建源码级层级提取逻辑位于 notion_hierarchy.py。由于 Notion API 只返回每个页面的直接父级additional_metadata.parent中可能为page_id、database_id或workspace三种类型不像 Confluence 那样返回完整祖先数组因此连接器需要extract_parent_id()解析单页的直接父 IDworkspace类型视为根节点无父级extract_ancestor_chain()沿着父链接向上遍历、重建完整祖先链并做环检测遇到已访问节点立即停止防止循环引用build_browse_path_v2()把祖先链转换为BrowsePathsV2方面为 DataHub UI 提供层级浏览路径当通过page_ids/database_ids限定摄取范围时这些 ID 会作为浏览路径锚点祖先链不会越过锚点向上延伸。这意味着只要hierarchy.enabled: true默认且父页面也在此次摄取范围内你就能在 DataHub 中按照 Notion 原始结构逐级浏览文档。对 Notion API 变更的兼容处理从 notion_source.py 可以看到连接器针对底层unstructured-ingest0.7.2 与 Notion API 的版本差异内置了多组 monkeypatch例如过滤 Page 类不认识的is_locked新字段为 20 余个数据库属性类过滤description字段在数据库 HTML 输出中补上数据库标题避免文档标题变成通用 ID绕过DatabasesEndpoint.super().query()的兼容性问题优雅处理 Synced Block、编号列表新字段、未知图标类型以及对全部FromJSONMixin类型类做通用未知字段过滤。这些补丁的共性设计是降级而非失败遇到新字段时丢弃该字段并记录一次性告警保证整批摄取不被中断——这是理解该源对 Notion API 频繁演进的健壮性设计的关键。状态化摄取内容哈希驱动的增量更新状态化摄取是本源的核心能力之一其工作机制为基于内容哈希的变化检测对应notion_source.py中的_initialize_state_tracking与文档状态跟踪计算「文档内容 嵌入配置」的 SHA-256 哈希与上一次运行保存的哈希比对检测变化仅当哈希变化时才重新处理该文档跟踪所有已产出 URN用于删除检测。实际运行效果首次运行处理全部文档后续运行只处理新增/变更的文档未变化的文档直接跳过页面被删除自动在 DataHub 中软删除对应实体。同时它继承自StatefulIngestionSourceBase支持stateful_ingestion.enabled: true的显式开启部分场景下为默认行为删除检测由StatefulStaleMetadataRemovalConfig支撑。摄取报告类 notion_report.py 会统计扫描/处理/跳过/失败的文件数、创建的文档数含文件夹文档、提取文本字节数、嵌入成功/失败数、跳过的 Synced Block 等指标便于在datahub ingest输出中定位问题。性能调优并行度设置processing: parallelism: num_processes: 4 # 提高以加速处理默认: 2 max_connections: 20 # 并发 API 连接数默认: 10官方建议小型工作区100 页num_processes: 2中型工作区100–1000 页num_processes: 4大型工作区1000 页num_processes: 8过滤配置filtering: min_text_length: 100 # 跳过过短页面默认: 50 skip_empty_documents: true # 跳过空页面默认: true分块优化chunking: strategy: by_title # 保留文档结构推荐 max_characters: 500 # 分块大小默认: 500 combine_text_under_n_chars: 100 # 合并小分块默认: 100限制与注意事项Notion API 限制速率限制付费工作区约 3 请求/秒免费工作区约 1 请求/秒访问范围集成只能看到显式共享的页面内容类型部分块可能无法完美提取如复杂嵌入、Synced Block——源码会跳过其内容并记录告警。性能考量大型工作区首次运行耗时较长嵌入生成会增加与内容量成正比的处理时间Unstructured API 与嵌入 Provider 可能产生费用。内容提取能力边界支持文本、标题、列表、代码块、表格、Callout、Toggle、引用等块类型有限支持嵌入、公式、文件提取为链接/引用不支持实时图表、看板/画廊/时间线等数据库视图。故障排查速查表Integration not found 或 Unauthorized 错误检查api_key是否正确应以secret_开头确认页面已共享给集成确认集成拥有 Read content 能力。内容为空或缺失确认页面包含文本skip_empty_documents: true默认会跳过空页面检查min_text_length过滤设置默认 50 字符期望子页面时确认recursive: true检查子页面未被单独限制访问。摄取缓慢提高processing.parallelism.num_processes默认 2本地处理可考虑partition_by_api: false代价是占用更多内存用page_ids限定范围避免摄取整个工作区首次运行必然较慢后续运行走增量更新。嵌入生成失败检查 Provider 的 API Key留意 Provider 自身的速率限制如 Cohere 约 10k 请求/分钟确认嵌入模型名对应当前 ProviderBedrock 场景确认 IAM 权限与 AWS 控制台已启用模型访问。状态化摄取不生效确认配置了stateful_ingestion.enabled: true检查 DataHub 连接源需要查询上一次运行的状态若使用文件状态确认状态文件路径可写在摄取输出中查找状态持久化日志。层级/父子关系缺失确认hierarchy.enabled: true默认开启检查父页面是否也被摄取确认recursive: true父页面必须对集成可访问。如果摄取失败请先验证凭据、权限、连通性与范围过滤再结合摄取日志中的源特定错误信息逐项调整配置。总结DataHub 的 Notion 数据源用一条 YAML Recipe 就能把整个工作区的文档资产接入统一元数据平台页面与数据库映射为 Document 实体、层级结构转换为可浏览路径、内容哈希驱动增量更新、可选嵌入开启语义搜索。其健壮性设计ID 规范化、未知字段降级、层级环检测让它在 Notion API 频繁演进的环境中依然稳定可用。相关参考材料官方源文档 README.md、前置说明、后置说明、完整示例 notion_to_datahub.yml以及服务端语义搜索配置。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考