Spaces:
Sleeping
Sleeping
| # 面试准备指南 (Interview Guide) | |
| 这份文档总结了本项目作为面试作品的核心亮点、技术深度以及常见问题的回答策略。 | |
| ## 🌟 核心亮点 (Why this project?) | |
| ### 1. 架构深度 (Architecture Depth) | |
| * **Agentic RAG**: 不仅仅是简单的向量检索，而是引入了**动态路由 (Dynamic Routing)**。系统能根据用户意图（如 ISBN 精确搜索 vs. 模糊语义搜索）自动选择最佳检索策略（BM25, Hybrid, Small-to-Big），展示了对 RAG 系统的精细化控制能力。 | |
| * **Stacking Ensemble (模型融合)**: 在 Ranking 阶段，没有止步于单一模型，而是实现了 **LightGBM + XGBoost + Logistic Regression** 的 Stacking 架构。这体现了对机器学习模型偏差与方差的理解，以及追求极致推荐效果的工程态度。 | |
| * **Vector Database**: 结合 ChromaDB 实现语义搜索，紧跟当前 LLM + Vector Store 的技术热点。 | |
| ### 2. 工程质量 (Engineering Excellence) | |
| * **性能优化 (Performance Optimization)**: | |
| * **问题**: 系统在并发场景下出现卡顿，且推理延迟较高。 | |
| * **解决**: | |
| 1. **Async/Await 陷阱**: 发现 FastAPI 的 `async` 路由中运行了 CPU 密集型任务（Pandas 操作），导致 Event Loop 阻塞。即使加上 `await` 也没用，必须去除非 IO 操作的 async 或使用线程池。改为同步 `def` 让 FastAPI自动利用线程池解决。 | |
| 2. **向量化重构**: 发现特征生成使用了 Python 原生 `for` 循环。重构为 Numpy/Pandas 的向量化 (Vectorized) 操作，利用 SIMD 指令集优势，将推理速度提升了约 10 倍。 | |
| 3. **单例模式**: 引入 `MetadataStore` 单例，避免每次请求重复加载 CSV，显著降低了内存占用和 I/O 开销。 | |
| * **可解释性 (Explainability)**: 集成了 **SHAP (SHapley Additive exPlanations)**。不再是推荐系统的“黑盒”，而是能实时给出“为什么推荐这本书”（例如：因为你喜欢作者 X，或者因为主要读这类书），这是区分初级项目和高级项目的重要特征。 | |
| ### 3. 完整性 (Completeness) | |
| * **Full Stack**: 前端 (React) + 后端 (FastAPI) + 数据流 (ETL) + 模型训练 (Train Scripts) + 部署 (Docker)。 | |
| * **DevOps**: 包含 Dockerfile 和完整构建脚本，具备生产部署能力。 | |
| --- | |
| ## 🗣️ 面试话术与 Q&A 策略 | |
| ### Q1: 你在项目中遇到的最大困难是什么？怎么解决的？ | |
| **建议回答**: | |
| > “最让我印象深刻的是**系统性能优化**的过程。 | |
| > 最初版本在处理高并发请求时，推理延迟很高，甚至会阻塞整个服务。 | |
| > 我通过两个层面解决了这个问题： | |
| > | |
| > 1. **架构层**: 我使用 Profiling 工具发现，FastAPI 的 `async` 接口中包含了大量的 Pandas 数据处理逻辑。因为 Python 的 `async` 是单线程协作式的，CPU 密集型任务会直接卡死 Event Loop。我将其重构为利用 FastAPI 线程池的非异步模式，解决了阻塞问题。 | |
| > 2. **代码层**: 我发现特征工程部分原本是用 Python 循环写的。我将其重构为 **Numpy 向量化** 操作，把时间复杂度从 O(N) 的 Python 解释器开销优化到了底层 C 语言级别的矩阵运算，最终将特征生成速度提升了 10 倍以上。” | |
| ### Q2: 为什么选择 Stacking 融合模型？直接用 LightGBM 不够吗？ | |
| **建议回答**: | |
| > “单一模型往往存在局限性。 | |
| > LightGBM 擅长处理类别特征和梯度提升，XGBoost 在正则化处理上表现很好。 | |
| > 通过 Stacking，我使用一个简单的逻辑回归 (Logistic Regression) 作为 Meta-Learner 来学习这两个强模型的输出。 | |
| > 这不仅能利用不同模型的优势（降低 Bias 和 Variance），还能提高系统的**鲁棒性**。在我的离线实验中，Stacking 相比单一 LightGBM 在 NDCG@10 指标上有明显提升。” | |
| ### Q3: 你的 RAG 系统有什么特别之处？ | |
| **建议回答**: | |
| > “我的 RAG 系统不是简单地 'Retrieve then Generate'。我设计了一个 **Agentic Router**。 | |
| > 它会先判断用户的意图：如果是搜书号，直接走精确匹配；如果是模糊描述，走语义索引；如果是复杂查询，会触发 Rerank 重排序。 | |
| > 这种动态策略解决了传统 RAG '查得准就不全，查得全就不准' 的痛点。” | |
| **Q1. 关于 Swing 算法的物理意义：** | |
| > "我看你用了 Swing 召回。你能直观解释一下，为什么 Swing 比传统的 UserCF 更能抗噪声？`1 / (alpha + |I_u ∩ I_v|)` 这个公式里的分母是在惩罚什么样的用户对？" | |
| > *(考察点：是否真正理解算法原理，还是只是调包。关键在于理解 Swing 惩罚了那些“原本就很相似”的小圈子用户，突出了 serendipity)* | |
| **Q2. 关于 RAG 的延迟优化：** | |
| > "你的报告提到 Hybrid Search + Rerank 耗时约 800ms。如果我们要把这个系统部署到抖音的搜索框，要求 P99 延迟在 200ms 以内，你会砍掉哪些环节？或者如何通过工程手段优化？" | |
| > *(考察点：工程思维。答案可能包括：并行请求、向量库量化 HNSW、Rerank 模型蒸馏、缓存热门 Query、异步加载详情等)* | |
| **Q3. SASRec 的应用细节：** | |
| > "在 `src/model/sasrec.py` 中，你使用了 Transformer。在推理（Inference）阶段，如果用户每点一本书我们都要刷新推荐，SASRec 的计算成本是很高的。你如何缓存用户的 Embedding 状态以避免每次从头计算整个序列？" | |
| > *(考察点：对深度学习模型线上推理（Inference）优化的理解。关键在于 KV Cache 或者增量计算)* | |
| **Q4. metadata_store 的 SQLite 高并发改造：** | |
| > "在 recommender.py 中，你提到了 'Zero-RAM mode' 并从 SQLite 读取元数据。在高并发场景下（QPS > 1000），SQLite 的磁盘 I/O 会成为致命瓶颈。**如果现在系统 QPS 暴涨 100 倍，除了加机器，你会怎么改造 metadata_store 的读写架构？**" | |
| > *(考察点：对存储层 scaling 的理解。评议：通常会用 Redis/Memcached 做热数据缓存，或使用 Cassandra/HBase 列式存储)* | |
| **建议回答**: | |
| > "我会分阶段改造 metadata_store： | |
| > | |
| > 1. **短期**：在 SQLite 前加 Redis 读缓存，对 ISBN 做 key-value 缓存。metadata 是静态/准静态数据，热门书籍命中率可到 80%+，SQLite 压力可下降一个数量级。 | |
| > 2. **中期**：抽象 MetadataStore 接口，实现 `CachedMetadataStore`（Redis + SQLite fallback），并新增 `get_book_metadata_batch()` 批量查询，减少 N 次往返变成 1 次。 | |
| > 3. **长期**：若仍不足，可将 metadata 迁移到 PostgreSQL 或 Cassandra，Redis 做热数据缓存。SQLite 退化为冷备份或离线数据源。 | |
| > | |
| > 核心思路：把 SQLite 从 '唯一真相源' 降级为 '冷数据源'，高频读写交给 Redis 或分布式存储。" | |
| > | |
| > **补充：Staging 写入**：freshness_fallback 的在线爬取写入 `online_books.db`（独立 SQLite），不污染 `books_processed.csv` 和主 `books.db`。既解耦训练数据污染，又避免写锁阻塞读（主库只读）。 | |
| > | |
| --- | |
| ## 🔬 深度技术问题 (Advanced Technical Q&A) | |
| ### Q5. ChromaDB/SQLite 内存与扩展性：千万级迁移 | |
| **问题**：你选择了 ChromaDB (embedded) 和 SQLite。这对于演示很好，但对于千万级 Item 的库（Spotify 级别），这不可行。**如何迁移到 Milvus/Qdrant？如何对 ANN 索引（HNSW）进行分片？** | |
| **考察点**：对向量数据库扩展性、分布式 ANN 的理解。 | |
| **建议回答**： | |
| > 当前架构（ChromaDB + SQLite）适合 20 万级数据和演示。千万级规模下存在以下瓶颈： | |
| > | |
| > **ChromaDB**：嵌入式、单机、索引加载到内存。10M × 384 维 × 4B ≈ 15GB 向量，HNSW 图结构可能再放大 10–50 倍，单机内存和 CPU 无法支撑。 | |
| > | |
| > **SQLite**：单文件、单写锁、磁盘 I/O 成为瓶颈。 | |
| > | |
| > **迁移策略**： | |
| > | |
| > 1. **抽象 VectorStore 接口**：在 `vector_db.py` 中抽象 `VectorStoreInterface`，实现 `ChromaVectorStore`、`QdrantVectorStore`、`MilvusVectorStore`，通过配置切换，便于迁移。 | |
| > 2. **选型**：Milvus 适合大数据、分析 + 检索、原生分布式；Qdrant 更轻量、纯向量检索。千万级两者皆可。 | |
| > 3. **迁移步骤**：导出 Chroma 的 (id, embedding, metadata) → 在 Milvus/Qdrant 创建 Collection、配置 HNSW 参数 → 批量 upsert → 配置切换。 | |
| > | |
| > **HNSW 分片**： | |
| > | |
| > - **按 ID 哈希分片**：`hash(id) % N` 分布到 N 个 shard，每 shard 内建 HNSW。查询时并发打 N 个 shard，各取 top_k，再 merge 取最终 top_k。 | |
| > - **按 embedding 聚类分片**：K-Means 聚类，query 先定位所属簇，只查少数 shard（减少查询范围，但需处理冷启动和数据倾斜）。 | |
| > - **利用 Milvus/Qdrant 内置能力**：两者都支持分布式分片，可直接使用其 Sharding 配置，无需自建。 | |
| > | |
| > **与 Q4 的衔接**：metadata_store 的 SQLite 按 Q4 方案改造（Redis + PostgreSQL/Cassandra）； sparse 检索 FTS5 可迁移到 Elasticsearch/Meilisearch 做 hybrid。 | |
| --- | |
| ### Q6. 负采样 (Negative Sampling) | |
| **问题**：你在 TECHNICAL_REPORT 中使用了 "Hard negative sampling from recall results"。这样做会不会导致 **False Negative** 问题（即把用户其实喜欢但没点击的物品当成了负样本）？在训练 DIN 或 LGBMRanker 时，你是如何平衡 Random Negatives 和 Hard Negatives 的比例的？这对模型收敛有什么影响？ | |
| **考察点**：对推荐系统训练数据构造的理解，以及负采样策略的 trade-off。 | |
| **建议回答**： | |
| > **False Negative 风险**：存在。Hard negatives 来自 Recall 的 top-50 中「不是正样本」的 item。这些 item 很可能是用户会喜欢但尚未交互的（未曝光、未点击、或未来会点击）。若被标成负样本，就会形成 False Negative。Leave-Last-Out 下，正样本是用户最后一次交互；Recall 中其他 item 可能是「未来正样本」，却被当作负样本训练。 | |
| > | |
| > **比例策略**：当前实现是「hard 优先，random 补齐」。`neg_ratio=4` 表示每个正样本 4 个负样本；先用 recall 中非正样本填满，不足时用 random 补齐。没有显式比例（如 2 hard + 2 random）。 | |
| > | |
| > **收敛影响**：Hard negatives 梯度更有信息量，但 False Negative 会误导模型。可考虑 Curriculum Learning（先 random 后 hard）、或显式控制 hard:random 比例做实验。 | |
| --- | |
| ### Q7. 实时性 (Real-time / Near-line) | |
| **问题**：SASRec 主要是离线训练的。在 Spotify 场景下，如果用户刚刚连续听了 3 首 "Heavy Metal"，我们希望下一首推荐立刻跟上这个兴趣变化。在目前的架构下，如何将用户的**实时交互序列**（还没落库到 CSV）注入到 SASRec 或 DIN 的推理过程中？需要在 `RecommendationService` 里增加什么逻辑？ | |
| **考察点**：对离线训练 / 在线推理架构的理解，以及 session-level 实时反馈的工程实现。 | |
| **建议回答**： | |
| > **当前架构**：SASRec 的 `user_seq_emb` 和 DIN 的 `user_sequences` 都来自预计算的 pkl 文件，无法利用 session 内实时交互。 | |
| > | |
| > **需要增加的逻辑**： | |
| > | |
| > 1. **SASRecRecall**：新增 `recommend(user_id, ..., real_time_seq=None)`。当 `real_time_seq` 非空时，将 `effective_seq = (离线序列 + real_time_seq)[-max_len:]` 送入 SASRec 做一次 forward，得到新 `u_emb`，再查 Faiss。 | |
| > 2. **DINRanker**：`predict(..., override_hist=None)`，用 `override_hist` 覆盖 `user_sequences.get(user_id)`。 | |
| > 3. **FeatureEngineer**：`generate_features_batch(..., override_seq=None)`，用 override 序列计算 `sasrec_score`、`sim_max` 等。 | |
| > 4. **RecommendationService**：`get_recommendations(..., real_time_sequence=None)`，收到 session 内最近交互的 ISBN 列表，合并后传给上述各模块。 | |
| > | |
| > **注意**：新 item 不在 `item_map` 时需 fallback；SASRec forward 有计算开销，可对 session 做短时缓存（如 5 分钟内相同 seq 复用 embedding）。 | |
| --- | |
| ### Q8. 评估指标：Diversity 与 Serendipity | |
| **问题**：目前关注的是 HR@10 和 NDCG。作为内容平台，发现推荐列表里全是热门书（Harry Potter 效应）。如果要求在不显著降低 Accuracy 的前提下，提升推荐结果的 **Diversity（多样性）** 和 **Serendipity（惊喜感）**，你会如何在 Ranking 阶段或 Rerank 阶段修改目标函数或逻辑？ | |
| **考察点**：对推荐系统多目标优化、trade-off 的理解，以及常见 diversity / serendipity 手段。 | |
| **建议回答**： | |
| > **Rerank 阶段（推荐优先）**： | |
| > | |
| > 1. **MMR（Maximal Marginal Relevance）**：`score = λ * relevance - (1-λ) * max_sim(candidate, already_selected)`，用 category 或 embedding 相似度，λ 控制 accuracy vs diversity。 | |
| > 2. **Category 多样性约束**：限制 top-k 中同一 category 最多 N 本（如 2–3 本）。 | |
| > 3. **Popularity 惩罚**：对高 `i_cnt` 的 item 降权，`score_adj = score / (1 + γ * log(1 + item_cnt))`。 | |
| > | |
| > **Ranking 阶段**： | |
| > | |
| > - 增加 diversity 相关特征（如 `category_coverage`、`popularity_penalty`）。 | |
| > - 多目标优化：`loss = NDCG_loss + α * (-diversity_score)`。 | |
| > | |
| > **Serendipity**：惩罚与用户历史过度相似的 item（如 `sim_max` 上限）；或引入「意外但合理」的 item（同大类不同子类、同一作者不同风格）。 | |
| > | |
| > **评估**：补充 ILSD、Category Coverage、Gini 等 diversity 指标，做 accuracy–diversity Pareto 曲线。 | |
| --- | |
| ## 📋 已知限制与改进方向 (Known Limitations & Improvement) | |
| ### Q9. "Research" 风格的代码残留 | |
| **现象**：代码库在向 production 演进过程中，仍保留了一些研究原型风格的痕迹。 | |
| #### 6.1 注释掉的代码与 print 语句 | |
| | 位置 | 问题 | 建议 | | |
| |------|------|------| | |
| | `scripts/model/evaluate.py:38-40` | 注释掉的 `service.ranker_loaded = False` 和 debug logger | 删除或移至 `if DEBUG` 分支 | | |
| | `src/ranking/features.py:470` | `if __name__` 中的 `print(df_feats.head())` | 改为 `logger.debug` 或删除 | | |
| | `src/services/recommend_service.py:282-286` | `if __name__` 中的硬编码 print | 保留（仅主程序入口），可改为 `logger.info` | | |
| | `src/recall/fusion.py`, `itemcf.py`, `usercf.py`, `item2vec.py` | 各模块 `if __name__` 中的 test print | 统一改为 `logger.info` 或移入测试脚本 | | |
| **原则**：调试输出应受 `DEBUG` 控制，或仅在 `__main__` 下使用 `logger`，避免裸 `print`。 | |
| #### 6.2 混合范式：Dict vs Pydantic / DataFrame | |
| **问题**：API 层使用 Pydantic 模型（`BookResponse`, `RecommendationResponse`），但内部大量传递 `Dict[str, Any]`，导致： | |
| - IDE 无法自动补全字段 | |
| - 类型检查失效，易出现 `KeyError`（如 `meta.get("title")` 拼写错误难以发现） | |
| - 与 pandas 脚本式风格混用（`df['user_id'].iloc[0]` 直接取数据） | |
| **典型分布**： | |
| | 层级 | 当前形态 | 涉及文件 | | |
| |------|----------|----------| | |
| | API 入/出 | Pydantic ✅ | `main.py`: `BookResponse`, `RecommendationResponse` | | |
| | 内部传递 | `Dict[str, Any]` | `recommendation_orchestrator`, `response_formatter`, `metadata_store`, `fallback_provider`, `reranker` | | |
| | 数据层 | `pd.DataFrame` + `iloc` | `recommend_service`, `recall/fusion`, `ranking/features` | | |
| **改进方向**： | |
| 1. **定义领域模型**：为书籍元数据、推荐结果引入 Pydantic 或 TypedDict： | |
| ```python | |
| class BookMetadata(BaseModel): | |
| isbn: str | |
| title: str | |
| authors: str | |
| description: str | |
| thumbnail: Optional[str] = None | |
| average_rating: float = 0.0 | |
| # ... | |
| ``` | |
| 2. **内层使用强类型**：`format_book_response(meta: BookMetadata, ...)` 替代 `meta: Dict[str, Any]`。 | |
| 3. **`__main__` 入口**：用 `BookMetadata.model_validate(row)` 或显式构造，避免 `df.iloc[0]` 直接当 dict 用。 | |
| **面试话术**： | |
| > "项目从研究原型迭代而来，内部仍有 `Dict[str, Any]` 和 pandas 脚本式写法。若继续演进，我会在核心推荐流向 Pydantic 或 TypedDict 迁移，减少 KeyError 并提升 IDE 支持；同时将 `__main__` 中的 print 统一为受 DEBUG 控制的 logger。" | |
| --- | |
| ## 🧠 Lessons Learned (If I started over) | |
| 以下内容按 BQ 可复述方式展开：每条都包含「情境 -> 行动 -> 结果 -> 反思」。 | |
| ### Architecture & Modeling | |
| 1. **路由策略：从规则优先到轻量分类器优先** | |
| - **情境**：早期路由主要依赖 regex 和启发式规则，面对短 query、书名 query、自然语言 query 边界不稳定，规则不断补丁。 | |
| - **行动**：补充了轻量 intent classifier（TF-IDF + LogisticRegression）并保留规则 fallback，形成「模型优先 + 规则兜底」。 | |
| - **结果**：路由鲁棒性提升，减少了仅靠 `len(words)` 这类脆弱规则导致的误判。 | |
| - **反思**：如果重来，我会在 v1 就把轻量分类器作为默认入口，把规则只用于 deterministic case（如 ISBN）。 | |
| 2. **模块边界：更早定义 orchestrator / service / data access** | |
| - **情境**：项目迭代过程中出现过 facade 与 orchestrator 职责重叠，导致调用链不够清晰，后期重构成本升高。 | |
| - **行动**：逐步把流程编排收敛到 orchestrator，业务逻辑放 service，数据读取放 store/repository，减少跨层依赖。 | |
| - **结果**：测试替身（DI）和问题定位更容易，改动影响面可控。 | |
| - **反思**：如果重来，我会在第一版就写清模块职责表，避免“能跑就先加一层”的结构漂移。 | |
| 3. **类型化：尽早建立领域模型而非大量 Dict 传递** | |
| - **情境**：原型阶段大量 `Dict[str, Any]` 传参，字段拼写错误或缺字段问题只能在运行时暴露。 | |
| - **行动**：引入 `TypedDict/Pydantic` 风格的数据契约（如 metadata 模型），让关键链路类型更明确。 | |
| - **结果**：接口语义更稳定，IDE 自动补全和重构可用性提升。 | |
| - **反思**：如果重来，我会把“类型边界”作为 API 与核心编排层的准入标准，而不是后补。 | |
| 4. **召回融合权重：从静态常量到持续校准对象** | |
| - **情境**：曾出现某一路召回权重过高（如 YoutubeDNN 2.0）压制其他信号，导致整体效果异常。 | |
| - **行动**：回退并重调权重（如降到 0.1），并结合误差分析定位“强通道掩盖弱通道”的问题。 | |
| - **结果**：指标从异常低谷恢复，召回融合更平衡。 | |
| - **反思**：如果重来，我会把权重治理产品化：固定评估面板 + 周期校准 + 异常报警，而非手工经验调参。 | |
| ### Evaluation & Experimentation | |
| 5. **评估防泄漏：先立规，再扩特征** | |
| - **情境**：评估阶段发现 favorites 过滤可能引入时间穿越，导致“系统把正确答案过滤掉”。 | |
| - **行动**：增加 `filter_favorites` 开关，明确 train-only 序列与 profile 的生成边界。 | |
| - **结果**：离线评估可信度提升，能区分“模型问题”与“评估配置问题”。 | |
| - **反思**：如果重来，我会先冻结评估协议（split、过滤、负采样）再做模型升级，避免指标噪音误导方向。 | |
| 6. **相关性定义：ISBN 命中与标题命中并行** | |
| - **情境**：系统做了版本去重（同标题不同 ISBN），但评估若只看 ISBN 会低估真实用户价值。 | |
| - **行动**：引入 title-relaxed 匹配作为补充口径，并在报告中同时说明严格口径与宽松口径。 | |
| - **结果**：指标解释力更强，能更贴近用户“找到了这本书”的真实感知。 | |
| - **反思**：如果重来，我会在项目初期就定义多层 relevance schema，避免后期口径争议。 | |
| 7. **行为信号：不只看 HR/MRR，还要看 engagement proxy** | |
| - **情境**：HR@10/MRR@5 更偏排序命中，无法全面反映用户满意度和长线价值。 | |
| - **行动**：规划补充隐式反馈（点击位次、dwell time、二跳点击）作为在线指标输入。 | |
| - **结果**：虽然目前仍以离线指标为主，但指标体系方向已从“命中率导向”走向“体验导向”。 | |
| - **反思**：如果重来，我会在第一版 API/日志结构里预留行为事件字段，降低后续埋点改造成本。 | |
| 8. **实验文化：从离线结论到在线 A/B 闭环** | |
| - **情境**：像 diversity reranker 这类策略，离线 coverage 提升不一定等价于在线 engagement 提升。 | |
| - **行动**：实现最小 A/B 框架（稳定分桶 + variant 配置 + exposure 日志），支持 control/treatment 对照。 | |
| - **结果**：具备了在线验证基础设施，后续可系统验证策略真实收益。 | |
| - **反思**：如果重来，我会更早把 A/B 能力作为平台能力接入，而不是特性上线后的补充。 | |
| ### Performance & Reliability | |
| 9. **分阶段延迟预算：把“快”拆解到每个环节** | |
| - **情境**：Hybrid + Rerank 提升相关性，但端到端延迟容易膨胀。 | |
| - **行动**：按 router / recall / rerank 分层预算，并加入 fast/async 开关来控制路径。 | |
| - **结果**：在质量与延迟之间可以按场景切换，而不是单一固定策略。 | |
| - **反思**：如果重来，我会在架构图里直接标注每段 latency budget，让优化从 day-1 可量化。 | |
| 10. **冷启动：从“兜底逻辑”升级为“核心场景”** | |
| - **情境**：新用户或低行为用户容易出现召回稀疏，导致推荐质量断崖。 | |
| - **行动**：逐步补齐 popularity fallback、onboarding 选书、recent_isbns 会话注入、intent probing。 | |
| - **结果**：冷启动从“无结果/低相关”改善为“可解释且可持续优化”的路径。 | |
| - **反思**：如果重来，我会把 cold-start 与 warm-start 分成两套明确策略，在 v1 同时设计。 | |
| 11. **Fallback 可观测：把兜底机制显式化** | |
| - **情境**：系统包含 freshness/web、metadata、model 等多类 fallback，若不可观测，问题定位困难。 | |
| - **行动**：在编排层与节点层加入 fallback 条件与日志，明确触发阈值和分支行为。 | |
| - **结果**：线上问题可快速判断是主路径退化还是 fallback 触发异常。 | |
| - **反思**：如果重来，我会统一 fallback reason code，并接入 dashboard，降低排障认知负担。 | |
| ### Data & Repo Hygiene | |
| 12. **数据与产物治理：目录规范越早越省成本** | |
| - **情境**：项目中后期根目录混入日志、快照、临时文件，影响协作与可维护性。 | |
| - **行动**：迁移到 `logs/`、`data/legacy_root_exports/`、`docs/archived/assets/` 并完善 `.gitignore` 白名单。 | |
| - **结果**：仓库入口清爽，构建/阅读路径更稳定。 | |
| - **反思**：如果重来，我会在项目初始化就定义 artifact policy（可追踪、可清理、可归档）。 | |
| 13. **文档与发布一致性：把文档更新纳入发布门禁** | |
| - **情境**：出现过“README 冻结说明”与 CHANGELOG `Unreleased` 语义冲突，给读者造成认知偏差。 | |
| - **行动**：统一为 post-freeze maintenance 口径，并建立 docs hub + archived index。 | |
| - **结果**：项目叙事一致，外部读者更容易理解“基线冻结但允许维护”的状态。 | |
| - **反思**：如果重来，我会把 README/CHANGELOG/docs 索引同步更新设置为 release checklist 的必选项。 | |
| --- | |
| ## 📈 关键指标 (Key Metrics) | |
| * **Hit Rate@10**: 0.4545 (v2.6.0, n=2000, Leave-Last-Out) | |
| * **MRR@5**: 0.2893 (Title-relaxed matching) | |
| * **Latency**: P99 < 50ms (Personalized Recs) | |