# F3_official_pipeline

**Repository Path**: cugjack/f3_official_pipeline

## Basic Information

- **Project Name**: F3_official_pipeline
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# F3测井—地震多模态官方模拟流水线

本目录是一套可直接上传Linux GPU服务器的完整示例。它把以下流程拆成按编号执行的
Python入口：

1. 任意数量测井LAS转四曲线标准CSV；
2. 使用预训练Stage1/Stage2生成测井融合码本；
3. F3 SEG-Y、断层解释和层位解释转换成SFM所需DAT数据与标签；
4. 分别训练纯地震基线和测井—地震融合模型；
5. 在独立test空间划分上推理断层和层位；
6. 输出预测NPY、概率、图片、指标和最终说明报告。

除输入目录外，所有 `--output-*` 参数均可省略。默认结果统一写入本目录的
`output/`，并按阶段和数据类型分子目录。

---

## 1. 建议上传后的目录结构

```text
服务器工作目录/
├── F3_official_pipeline/                  # 本代码包
│   ├── scripts/                           # 按编号执行的入口
│   ├── converters/                        # F3 SEG-Y/解释数据转换实现
│   ├── vendor/
│   │   ├── clean_data/                    # 报告第三章完整九曲线清洗代码
│   │   ├── well_stage12/                  # Stage1/Stage2训练与模型定义
│   │   └── sfm/                           # SFM训练、融合与评估源码
│   ├── models/
│   │   ├── well/
│   │   │   ├── stage1_best.pt
│   │   │   ├── stage2_best.pt
│   │   │   └── stage1_codebook.npy
│   │   └── seismic/SFM-Base.pth
│   ├── models/MODEL_MANIFEST.json           # 模型大小与SHA256
│   ├── example_data/F3_Demo_2023/       # 已随包附带的最小F3示例数据
│   └── output/                            # 自动生成；可不上传
```

包内已经附带转换和验证所需的最小F3解释与测井示例数据。由于公共版
Gitee仓库不支持Git LFS，大体积SEG-Y文件不纳入Git提交；请单独上传或
复制地震文件到下列固定位置：

`example_data/F3_Demo_2023/Rawdata/Seismic_data.sgy`

完整输入目录结构如下：

```text
F3_Demo_2023/
├── .survey
└── Rawdata/
    ├── Seismic_data.sgy
    ├── Faults/FaultA.txt
    ├── Surface_data/F3-Horizon-*.txt
    └── Well_data/All_wells_RawData/Lasfiles/*.las
```

---

## 2. 环境安装

建议Python 3.10或3.11。先按服务器CUDA版本安装PyTorch，再安装其余依赖：

```bash
cd F3_official_pipeline

# 示例；实际CUDA命令以 pytorch.org 为准
# python -m pip install torch --index-url https://download.pytorch.org/whl/cu124

python -m pip install -r requirements.txt
python -m pip install -e vendor/sfm
```

检查环境、权重和默认F3目录：

```bash
python scripts/00_check_environment.py
```

检查结果保存到：

```text
output/environment_report.json
```

出现 `CHECK_OK` 后再继续。

---

## 3. 第一步：测井LAS转CSV

### 3.1 F3四口示例井

```bash
python scripts/01_prepare_well_csv.py --well-type f3
```

`--well-type`：

- `f3`：优先使用 `GR,RHOB,DT,PHIE`，映射为 `GR,DEN,AC,CNL`；
- `standard4`：优先读取已经命名为 `GR,DEN,AC,CNL` 的LAS。

代码不会写死井数。输入目录中有多少个LAS，就输出多少个CSV。LAS位于多层子目录时
增加 `--recursive`。

默认输出：

```text
output/well_csv/
├── <井名1>.csv
├── <井名2>.csv
└── manifest.json
```

CSV固定契约：

```text
WELL,DEPTH,GR,DEN,AC,CNL
```

处理内容包括NULL识别、线性插值、首尾补齐、深度排序去重、0.1米重采样和曲线别名
映射。CSV保留物理数值；每井z-score在下一步执行。

指定自定义输出：

```bash
python scripts/01_prepare_well_csv.py \
  --las-dir /data/official/wells \
  --output-dir /data/run01/well_csv \
  --well-type standard4 \
  --recursive
```

已有同名CSV时，明确增加 `--overwrite` 才会覆盖。

### 3.2 报告第三章完整清洗代码

`vendor/clean_data/` 保留了报告第三章的P1～P5完整九曲线清洗：异常值、公共有效
深度、电阻率一致性、KNN/随机森林插补和FLAG。它面向延安九曲线
`SP,GR,CAL,CNL,DEN,AC,M2R3,M2R6,M2R9` 的训练数据复现：

```bash
python vendor/clean_data/main.py --input-dir /data/yanchang_las
```

它不作为F3四曲线官方推理的前置命令；F3缺少其中五条曲线。正式评测使用上面的
`01_prepare_well_csv.py`。

---

## 4. 第二步：生成测井融合码本

```bash
python scripts/02_build_well_memory.py \
  --csv-dir output/well_csv \
  --well-type f3
```

默认自动使用：

```text
models/well/stage1_best.pt
models/well/stage2_best.pt
models/well/stage1_codebook.npy
```

计算过程：

```text
CSV按井z-score
→ Stage1冻结编码
→ 通过K=2048 Stage1码本生成token_id
→ Stage2冻结上下文编码
→ 导出每个token的768维hidden_states
→ 汇总全部井
→ MiniBatchKMeans(K=128)
```

默认输出：

```text
output/well_memory/
├── cluster_centers.npy          # [128,768] float32，给SFM融合训练
└── cluster_centers_meta.json    # 井数、井名、token数、模型来源
```

如需审计每口井聚类前的特征：

```bash
python scripts/02_build_well_memory.py \
  --csv-dir output/well_csv \
  --well-type f3 \
  --save-token-features
```

这会额外生成 `output/well_memory/token_features/*.npy`。

### 为什么除了两个PT还要 `stage1_codebook.npy`

Stage1 checkpoint生成连续向量，`stage1_codebook.npy [2048,256]` 负责把连续向量
转换成Stage2需要的离散token编号。因此冻结推理的最小模型集合是：

```text
stage1_best.pt + stage2_best.pt + stage1_codebook.npy
```

Stage2训练包中的训练井token、深度、split和offset等NPY不需要交给官方推理。

### 可选：重新训练测井Stage1/Stage2

官方通常跳过。若需用大量同契约CSV复现训练：

```bash
python scripts/optional_train_well_models.py \
  --csv-dir /data/cleaned_training_csv \
  --gpu-list 0,1,2,3 \
  --stage1-epochs 100 \
  --stage2-epochs 75 \
  --skip-install
```

训练代码位于 `vendor/well_stage12/`。完成后选中的三项模型会复制回
`models/well/`。此训练入口接受有无 `LABEL` 的CSV，因为Stage1/Stage2本身是自监督。

---

## 5. 第三步：SGY、断层和层位转DAT

同时生成两个任务：

```bash
python scripts/03_prepare_seismic_dat.py --task all
```

只生成一个任务：

```bash
python scripts/03_prepare_seismic_dat.py --f3-root ../F3_Demo_2023 --task fault
python scripts/03_prepare_seismic_dat.py --f3-root ../F3_Demo_2023 --task horizon
```

已有结果需重建时增加 `--overwrite`。

默认输出：

```text
output/seismic_dat/
├── F3Fault/
│   ├── seismic/<id>.dat
│   ├── label/<id>.dat
│   ├── valid/<id>.dat
│   ├── splits/{train,val,test}.txt
│   ├── index.csv
│   ├── metadata.json
│   └── pipeline_dataset.json
└── F3Horizon/
    └── 同上
```

DAT标准：

- `224×224`；
- 无header、float32；
- seismic为逐样本百分位裁剪后z-score；
- label为0/1 float32；
- valid为有效SEG-Y道掩码；
- 文件编号连续，顺序严格为train→val→test。

F3默认预期数量：

| 数据集 | train | val | test | 总计 |
|---|---:|---:|---:|---:|
| F3Fault | 81 | 18 | 18 | 117 |
| F3Horizon | 540 | 120 | 100 | 760 |

断层标签来自FaultA的13条fault sticks；层位标签合并7个解释层面，任务均为“是否属于
断层/层位边界”的二分类，而不是识别具体断层名或层位名。

---

## 6. 第四步：地震下游微调

该步骤需要GPU。训练严格使用train，checkpoint选择使用val，test不会参与训练和选模。

### 6.1 两轮冒烟测试

先用单独输出目录验证环境和显存：

```bash
python scripts/04_train_seismic.py \
  --task all \
  --mode both \
  --gpu 0 \
  --epochs 2 \
  --output-root output/smoke_training
```

这会依次训练：

```text
断层 baseline
断层 fusion
层位 baseline
层位 fusion
```

显存不足时增加较小batch，例如：

```bash
--batch-size 8
```

### 6.2 正式训练

```bash
python scripts/04_train_seismic.py \
  --task all \
  --mode both \
  --gpu 0 \
  --epochs 600 \
  --warmup-epochs 60
```

如果只训练某一项：

```bash
python scripts/04_train_seismic.py --task fault   --mode baseline --gpu 0 --epochs 600
python scripts/04_train_seismic.py --task fault   --mode fusion   --gpu 0 --epochs 600
python scripts/04_train_seismic.py --task horizon --mode baseline --gpu 0 --epochs 600
python scripts/04_train_seismic.py --task horizon --mode fusion   --gpu 0 --epochs 600
```

默认训练结果：

```text
output/seismic_training/
├── F3Fault/
│   ├── baseline/checkpoint-best.pth
│   └── fusion/checkpoint-best.pth
├── F3Horizon/
│   ├── baseline/checkpoint-best.pth
│   └── fusion/checkpoint-best.pth
└── training_manifest.json
```

每个run目录还包含 `config.yaml`、`log.txt`、TensorBoard日志及阶段checkpoint。

`baseline` 只使用地震DAT；`fusion` 使用同一批地震数据和标签，同时读取
`output/well_memory/cluster_centers.npy`。测井码本不是标签，融合模型仍必须使用地震
像素标签完成微调。

断点继续时使用相同输出目录并增加 `--resume`。

---

## 7. 第五步：测试集推理

正式训练完成后执行：

```bash
python scripts/05_predict_seismic.py \
  --task all \
  --mode both \
  --split test \
  --gpu 0
```

默认输出四组结果：

```text
output/predictions/
├── F3Fault/
│   ├── baseline/
│   └── fusion/
└── F3Horizon/
    ├── baseline/
    └── fusion/
```

每组包含：

```text
samples.png                    # 地震切片/人工标签/预测图
predictions.npy                # [N,224,224] 二值预测
positive_probabilities.npy     # [N,224,224] 正类概率
sample_ids.npy                 # 对应原DAT编号
metrics.json                   # mIoU、IoU、F1、Precision、Recall等
RESULT.md                      # 中文结果说明
```

可选水平翻转TTA：

```bash
python scripts/05_predict_seismic.py --task all --mode both --split test --gpu 0 --tta
```

没有GPU时可用 `--cpu`，但SFM-Base推理会明显变慢。

---

## 8. 第六步：汇总最终报告

```bash
python scripts/06_build_report.py
```

默认输出：

```text
output/final_report/
├── FINAL_REPORT.md
├── metrics_comparison.png
└── all_metrics.json
```

报告同时比较：

- 断层：baseline vs fusion；
- 层位：baseline vs fusion；
- mIoU、正类IoU、正类F1、Precision和Recall。

---

## 9. 默认 `output/` 全部中间文件和结果

```text
output/
├── environment_report.json
├── well_csv/                   # 第一步中间CSV
├── well_memory/                # 第二步测井码本
├── seismic_dat/                # 第三步DAT、标签、划分和来源信息
├── seismic_training/           # 第四步正式模型checkpoint
├── smoke_training/             # 可选两轮冒烟训练
├── predictions/                # 第五步四组预测、图片和指标
└── final_report/               # 第六步总报告
```

更换任一阶段的输出目录后，下一阶段必须通过对应参数指向新目录：

- `02`：`--csv-dir`；
- `04`：`--data-root --well-memory --output-root`；
- `05`：`--data-root --training-root --output-root`；
- `06`：`--prediction-root --output-dir`。

---

## 10. 最短完整命令清单

```bash
cd F3_official_pipeline
python -m pip install -r requirements.txt
python -m pip install -e vendor/sfm

python scripts/00_check_environment.py

python scripts/01_prepare_well_csv.py --well-type f3

python scripts/02_build_well_memory.py \
  --csv-dir output/well_csv \
  --well-type f3

python scripts/03_prepare_seismic_dat.py --task all

python scripts/04_train_seismic.py \
  --task all --mode both --gpu 0 --epochs 600 --warmup-epochs 60

python scripts/05_predict_seismic.py \
  --task all --mode both --split test --gpu 0

python scripts/06_build_report.py
```

完成标志：

```text
output/well_memory/cluster_centers.npy              [128,768]
output/seismic_training/F3Fault/*/checkpoint-best.pth
output/seismic_training/F3Horizon/*/checkpoint-best.pth
output/predictions/F3Fault/{baseline,fusion}/samples.png
output/predictions/F3Horizon/{baseline,fusion}/samples.png
output/final_report/FINAL_REPORT.md
output/final_report/metrics_comparison.png
```

---

## 11. 适用范围与注意事项

1. 当前预训练测井模型的输入契约固定为四种物理曲线：`GR,DEN,AC,CNL`。井数动态，
   但不能把任意四条不同物理含义的曲线按位置强行输入。
2. F3只有4口示例井，测井码本是目标工区先验；它不包含井位到地震像素的显式空间
   对齐。
3. F3只提供一个明确解释断层和7个层位面，未标注位置不一定是真正的地质负样本。
4. `cluster_centers.npy` 不是最终任务模型；它必须在fusion下游微调中与地震标签共同
   使用。
5. test划分只用于最终推理和报告，不能用于调参、训练或选择checkpoint。