機密等級: 內部技術文件
目的: 記錄技術細節、已踩過的坑、以及關鍵決策原因
日期: 2025-10-16 狀態: 已實施 決策: 採用 step1-4 分離式管線而非單一腳本
原因:
- 便於 debug 單一步驟
- 可以快取中間結果（features/*.csv）
- 允許並行開發不同模組
後果:
- ✅ 維護更容易
- ❌ 需要管理檔案 I/O
日期: 2025-10-16 狀態: 已解決 問題: FoldX 在 Windows 下經常 timeout 或返回全 0
根本原因:
- 突變格式錯誤（使用 SA262K 而非 NA233K）
- PDB 編號偏移（序列從 1 開始，PDB 從 30 開始）
- Windows 路徑包含空格導致解析失敗
解決方案:
# 正確的突變格式
mutation = f'{wt_aa}A{pdb_position}{mut_aa}' # e.g., 'NA233K'
# PDB 位置計算
pdb_position = sequence_position + 30 # PDB offset
# Windows 路徑處理
work_dir = Path(tempfile.mkdtemp(prefix='foldx_'))# ❌ 錯誤：直接傳入序列
tokens = tokenizer(sequence)
# ✅ 正確：需要加空格
spaced_sequence = ' '.join(sequence)
tokens = tokenizer(spaced_sequence)# ❌ 錯誤：使用 FASTA 格式
# GEMME 無法讀取
# ✅ 正確：使用 A3M 格式
# 包含 gap 信息的 aligned FASTA# ❌ 錯誤：所有特徵都正規化
features_normalized = (features - mean) / std
# ✅ 正確：考慮方向性
if 'ddg' in column_name: # Lower is better
features[column] = -features[column] # 反轉# ❌ 錯誤：會觸發 SettingWithCopyWarning
df[df['score'] > 0]['normalized'] = 1.0
# ✅ 正確：使用 .loc
df.loc[df['score'] > 0, 'normalized'] = 1.0# PETase (5XJH.pdb) 的映射
SEQUENCE_START = 1 # 序列編號從 1 開始
PDB_START = 30 # PDB 編號從 30 開始
OFFSET = 29 # 固定偏移量
# 重要突變位置（序列編號 → PDB 編號）
mutations_map = {
'N233K': 'NA233K', # N at 233 → K
'S121E': 'SA121E', # S at 121 → E
'R224Q': 'RA224Q', # R at 224 → Q
}# 使用特定版本避免相容性問題
MODEL_VERSIONS = {
'esm2': 'facebook/esm2_t33_650M_UR50D',
'esm2_small': 'facebook/esm2_t6_8M_UR50D', # 記憶體不足時
'protbert': 'Rostlab/prot_bert',
'saprot': 'westlake-repl/SaProt_650M_AF2'
}
# 快取策略
import os
os.environ['TRANSFORMERS_CACHE'] = './cache/models'
os.environ['HF_HOME'] = './cache/huggingface'瓶頸 1: ESM2 推論速度
# 問題：逐序列處理太慢
for seq in sequences:
predict(seq) # 10 序列需要 5 分鐘
# 解法：批次處理
batch_size = 8
for batch in DataLoader(sequences, batch_size=batch_size):
predict_batch(batch) # 10 序列只需 1 分鐘瓶頸 2: FoldX 單執行緒
# 問題：FoldX 不支援多執行緒
# 解法：使用 multiprocessing
from multiprocessing import Pool
def run_foldx_parallel(mutations):
with Pool(processes=4) as pool:
results = pool.map(calculate_ddg, mutations)
return results序列長度: 300 aa
關鍵區域:
- 活性位點: S160, H237, D206 (催化三聯體)
- 底物結合: W159, Y87, M161
- 熱穩定性: 二硫鍵 C203-C239
已知有益突變:
- S121E: 提升活性 (文獻證實)
- N233K: 提升熱穩定性
- I208V: 提升表達
需避免區域:
- 催化三聯體 (必須保守)
- 疏水核心 (影響折疊)FEATURE_IMPORTANCE = {
'gemme_score': 0.35, # 最重要（待實施）
'esm2_masked_marginal': 0.25,
'foldx_ddg': 0.15,
'conservation_score': 0.10,
'hydrophobicity': 0.08,
'charge_distribution': 0.05,
'secondary_structure': 0.02
}# 使用已知突變測試
python scripts/validate_with_known.py \
--mutations "S121E:high_activity,N233K:high_stability"
# 應該看到
# S121E: activity_rank > 80th percentile ✓
# N233K: stability_rank > 80th percentile ✓# 已實作但未文檔化的快取
from pipeline.utils import FeatureCache
cache = FeatureCache('features/cache/')
features = cache.get_or_compute('esm2_embeddings',
compute_func=calculate_esm2)# 啟用詳細日誌
import os
os.environ['PIPELINE_DEBUG'] = '1'
os.environ['FOLDX_VERBOSE'] = '1'data/validation_set/ # 包含 10 個已知活性的突變
data/literature_validated/ # 文獻驗證的 15 個突變
-
不要直接修改
features/*.csv- 這些是生成的檔案，會被覆蓋
- 如需修改，改源代碼
-
不要使用 PETase 實驗數據訓練
- 違反 Zero-shot 規則
- 會被取消資格
-
不要硬編碼路徑
# ❌ 錯誤 path = "C:\\Users\\thc1006\\..." # ✅ 正確 path = Path(__file__).parent / 'data'
-
不要忽略 Windows 相容性
- 專案需要在 Windows 上運行
- 使用 pathlib.Path 而非字串路徑
# 1. 清理快取
rm -rf cache/ features/*.csv temp/
# 2. 重置環境
conda deactivate
conda env remove -n petase
conda create -n petase python=3.10
pip install -r requirements.txt
# 3. 驗證基本功能
python scripts/minimal_test.py
# 4. 重新生成特徵
python pipeline/regenerate_all_features.py| 錯誤訊息 | 原因 | 解法 |
|---|---|---|
CUDA out of memory |
GPU 記憶體不足 | 使用較小 batch 或 CPU |
FileNotFoundError: foldx |
FoldX 路徑錯誤 | 檢查 tools/foldx/ |
KeyError: 'sequence_id' |
欄位名不一致 | 統一使用 'id' |
ValueError: NaN in features |
特徵計算失敗 | 檢查輸入序列 |
當前基準: ρ = 0.224
預期提升:
GEMME: +0.15 # 最大提升
SaProt: +0.10
Perplexity權重: +0.08
Ensemble優化: +0.05
Inference Dropout: +0.05
目標總和: ρ > 0.70可接受:
單序列預測: < 10 秒
100 序列批次: < 5 分鐘
完整管線: < 30 分鐘
當前耗時:
ESM2 (650M): ~2 秒/序列
FoldX: ~10 秒/突變
特徵融合: < 1 秒# Step 1: 準備環境
cd tools/
git clone https://github.com/simonhaffner/GEMME.git
cd GEMME
# 注意：需要 g++ 和 Python 2.7（是的，很舊）
# Step 2: 生成 MSA
# 方法 A: 使用 jackhmmer (慢但準)
jackhmmer -N 5 -E 0.001 --cpu 8 \
-A petase.sto petase.fasta uniref30.fasta
# 方法 B: 使用 MMseqs2 (快)
mmseqs easy-search petase.fasta uniref30 result.m8 tmp
# Step 3: 轉換格式
python scripts/convert_to_gemme_format.py \
--input petase.sto \
--output petase_gemme.txt
# Step 4: 運行 GEMME
python $GEMME_PATH/run_gemme.py \
--alignment petase_gemme.txt \
--output gemme_scores.txt# scripts/phase2/add_saprot.py
from transformers import EsmModel, AutoTokenizer
# 載入模型
model = EsmModel.from_pretrained("westlake-repl/SaProt_650M_AF2")
tokenizer = AutoTokenizer.from_pretrained("westlake-repl/SaProt_650M_AF2")
# 準備結構序列（3Di 格式）
structure_seq = convert_to_3di(pdb_file) # 需要實作
combined_seq = f"{protein_seq}#{structure_seq}"
# 推論
inputs = tokenizer(combined_seq, return_tensors="pt")
outputs = model(**inputs)
embeddings = outputs.last_hidden_state.mean(dim=1)您接手的是一個 40% 完成度的專案，基礎架構都已經搭建好：
已完成的基礎很扎實:
- ✅ 管線架構完整
- ✅ 測試框架完善
- ✅ 主要 bug 已修復
待完成的部分明確:
- ⏳ GEMME 整合（最關鍵）
- ⏳ 多模型 ensemble
- ⏳ 進階優化技術
成功關鍵:
- 不要重寫現有代碼，而是擴展
- 優先實作 GEMME（預期最大提升）
- 保持 Zero-shot 原則
- 記得測試 Windows 相容性
如果全職投入：
- 2 週可完成 Phase 2（達到 ρ=0.50）
- 4 週可完成 Phase 3（達到 ρ=0.70）
- 6 週可完成所有優化（爭取前三名）
如果兼職投入：
- 時間翻倍，但仍可趕上截止日期
祝您順利！相信您能帶領專案奪冠！ 🏆
文檔版本: 1.0.0 | 最後更新: 2025-10-16 | 作者: Claude Code