diff --git a/src/llm/predict.py b/src/llm/predict.py
index c582df4..7220571 100644
--- a/src/llm/predict.py
+++ b/src/llm/predict.py
@@ -1,4 +1,16 @@
-"""预测服务:拼上下文 → 调 LLM → 存预测。"""
+"""预测服务:拼上下文 → 调 LLM → 存预测。
+
+落库层级(table: predictions):
+
+| 模式      | 落库位置(服务层)                                            | 路由层(routes/predict.py) |
+|-----------|-------------------------------------------------------------|---------------------------|
+| single    | `_predict_single` → `_upsert_prediction`                    | 不读 DB,仅映射 result → PredictOut |
+| multi     | `orchestrator.predict_match_multi` → `_upsert_prediction`   | 不读 DB,仅映射 result → PredictOut |
+| baseline  | `predict_baseline` → `_upsert_prediction`                   | 不读 DB,仅映射 result → PredictOut |
+
+三种模式统一在服务层经 UnitOfWork 落库并回填真实 prediction_id;
+路由层永不写入 predictions,只读 result.prediction_id 做响应映射。
+"""
 from __future__ import annotations
 
 import functools