将 Git 与 Lakeflow 作业配合使用

作业任务可以直接从远程 Git 存储库检出源代码。

以下任务类型支持远程 Git 存储库：

• Notebooks
• Python脚本
• SQL 文件
• 数据生成工具 （dbt） 项目

作业中的所有任务都必须引用远程存储库中的同一提交记录。 作业运行开始时，Azure Databricks 会对指定的分支或提交进行快照，以便该运行中的所有任务都能够使用相同的代码版本。

查看运行存储在远程 Git 存储库中的代码的任务的运行历史记录时， “任务运行详细信息 ”窗格包括 Git 详细信息，包括与运行关联的提交 SHA。 请参阅查看任务运行历史记录。

Git 存储库源与 Git 文件夹

本页讨论可以直接从远程 Git 存储库拉取源代码的任务。 工作区还支持名为 Git 文件夹的功能，其中工作区中的文件夹与 Git 存储库同步。 任务可以使用 Git 文件夹作为其源。 但是，必须管理与存储库的同步。 如本处所述，使用远程 Git 存储库会在作业运行时自动拉取新的源码（如果可用）。

Azure Databricks建议仅引用 Git 文件夹中的工作区路径，以便在开发期间进行快速迭代和测试。 对于过渡和生产作业，请配置任务以改为引用远程 Git 存储库。

为任务配置 Git 提供商

作业 UI 有一个用于配置远程 Git 存储库的对话框。 可从 Git 标题下的“作业详细信息”窗格或配置为使用 Git 提供程序的任何任务中访问此对话框。 若要访问对话框，请单击“作业详细信息”窗格中的“添加 Git 设置”。

在 “Git ”对话框中（如果在任务配置期间访问了 Git 信息 ），请输入以下详细信息：

• Git 存储库 URL。
• 从下拉列表中选择 Git 提供程序 。
• 在“Git 引用”字段中，输入与要运行的源代码版本对应的分支、标记或提交标识符。
• 从下拉列表中选择 分支、 标记或 提交 。

必须仅指定以下项之一：

• “分支”：分支的名称，例如 main。
• 标记：标记的名称，例如 release-1.0.0。
• “提交”：特定提交的哈希值，例如 e0056d01。

查看运行存储在远程 Git 存储库中的代码的任务的运行历史记录时， “任务运行详细信息 ”窗格包括 Git 详细信息，包括与运行关联的提交 SHA。 请参阅查看任务运行历史记录。

以角色身份运行 Git 作业

如果工作区使用 RBAC，则可以将作业的 运行身份 设置为组（角色）。 然后，该作业使用 角色的 Git 凭据克隆其 Git 存储库，因此管理器必须先配置该凭据，否则作业无法克隆。 若要将作业的 运行身份 设置为组，请参阅 将运行身份设置为组。

若要修复因代码问题而失败的作业，请在该作业的仓库和分支上使用其中一种 编写方法。 假设该角色可重现并针对角色的数据修复问题，提交修补程序，然后重新运行作业。

大型存储库的稀疏检出

对于大型存储库，您可以使用稀疏检出，仅导入特定目录，而非整个存储库。 稀疏检出可减少每次作业运行的检出时间和资源消耗。

但是，不正确的配置可能会导致缓存碎片，这会在整个工作区中降低执行时间。 本节介绍了使用稀疏检出时可能出现的权衡和问题。

Azure Databricks 如何缓存存储库检出

Azure Databricks 根据四个值对每个 Git 签出进行缓存：

• Workspace
• 存储库 URL
• 精确提交哈希
• 稀疏检出模式的指纹（确切的文件夹路径集）

与所有四个条件匹配的任何作业都会重复使用缓存条目，该条目最长有效期为一周。 例如，如果你有 3 个不同的作业，并且它们都具有相同的条件，那么它们会对该存储库使用同一个缓存，直到出现新的提交（或一周后）。

每个唯一稀疏签出模式都会创建单独的指纹，因此会创建单独的缓存条目。 如果每个 20 个用户将自定义文件夹添加到其模式，则系统会创建 20 个不同的缓存键并导入共享文件夹树 20 次，从而在工作区上增加负载。 创建一个包含其所有 20 个文件夹的稀疏签出模式（例如，将其作为一个父文件夹），这将允许单个缓存更频繁地工作，并在作业中提高性能。 其权衡在于检出中的文件数量会增加。

决定是否使用稀疏签出

仅当您的用例同时满足以下两个条件时，才应启用稀疏检出：

• 大小：存储库很大（例如，它超过 2,500 个文件）。
• 目标稳定：目标分支更新频率较低（例如，每小时约一次提交或更少）。 请避免因自动化 CI/CD 工作流而快速变化的分支。

如果使用稀疏检出，您的组织还应采用以下一种或两种模式策略：

• 标准化：在整个组织中使用三种或更少的共享签出模式来最大程度地提高缓存命中率。
• 微目标定位：调整结构模式，以使每个模式专注于少量文件。 为了获得最佳性能，目标少于 200 个文件。

这有助于降低进口率。

计算导入率

在启用稀疏检出之前，请估算预计的每小时文件数导入速率。 限制在工作区级别对所有任务和用户统一适用。

每小时文件数 = 每小时任务运行次数 × 缓存未命中率 × 每次未命中导入的文件数

示例：180 次运行/小时× 10% 错率× 6,000 个文件/小时 = 108,000 个文件/小时

将结果与以下阈值进行比较：

最佳做法

标准化模式

• 建议：每个仓库发布三个或更少的已批准稀疏模式。 共享模式合并负载并最大化缓存命中数。
• 不要：禁止每个团队自定义模式。 即使是一个额外的文件夹也会创建新的缓存条目，并触发完全的重新导入。

管理提交更替

• 建议：将任务指向稳定的发布分支。 将合并操作批量安排在预定的发布窗口内，以便多次运行共享相同的缓存提交。
• 不建议：在 master 或 main 等频繁更新的分支上使用稀疏检出。 由于缓存是基于确切的提交哈希，因此每次新提交都会使缓存失效，并导致每个作业运行时需要完全重新导入。

管理负载

• Do：从源代码管理中删除大型二进制文件、生成的项目和数据文件，以无条件地减小存储库大小。
• 请勿使冗余作业以高频率运行。 对于不需要连续执行的任务，应降低触发频率、错开调度时间，或合并使用相同检出点的任务。

通过发布分支管理提交变动

当任务针对 master 或 main 这样的快速变动分支时，提交哈希值会频繁变化，导致几乎每次运行都会发生缓存未命中。 使用按固定计划进行更新的专用发布分支可提高缓存命中率。

通过将所有任务指向按小时划分的发布分支，该小时内所有运行都会解析为相同的提交哈希值，并共享相同的缓存条目。

配置发布分支：

1. 在 Git 存储库中创建生存期较长的分支（例如 release-candidate）。
2. 按固定时间表（例如每整点）自动更新此分支，使其与 master 保持一致。
3. 配置基于 Git 的任务，使其将 release-candidate 作为目标 Git 引用。

在实现之前，请查看以下权衡：

示例：使用 GitHub Actions 自动执行

以下 GitHub Actions 工作流可自动执行每小时的发布分支切分。

步骤 1：将 .github/workflows/cut-release-branch.yml 文件提交到存储库：

name: Cut Hourly Release Candidate

on:
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-branch:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout main branch
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: Update release-candidate branch
        run: |
          git push origin HEAD:release-candidate --force

Step 2：手动触发GitHub操作以验证是否已创建 release-candidate 分支。

步骤 3：更新现有作业以 release-candidate 用作目标 Git 引用。

使用作业 API 启用稀疏签出

要启用稀疏检出，请在创建或更新作业时在 sparse_checkout 中包含一个 git_source 代码块：

{
  "git_source": {
    "git_url": "https://github.com/example/my-repo",
    "git_provider": "gitHub",
    "git_branch": "release-candidate",
    "sparse_checkout": {
      "patterns": ["src/models", "src/utils"]
    }
  }
}

每个 patterns 字符串都是相对于存储库根目录的目录路径。 每个指定目录中的所有文件都包含在签出中。