从 472ms 到 150ms：Hindsight 的 SQL 模板为何能超越 Text2SQL

Query → Embedding(84ms) → 4-way Parallel(352ms) → RRF(2ms) → Rerank(3ms) → Token Filter(4ms)

# engine/sql/base.py（节选，实际 200+ 行接口）
class SQLDialect(ABC):
    @abstractmethod
    def param(self, n: int) -> str: ...          # 参数占位符：PG 是 $1，Oracle 是 :1
    @abstractmethod
    def vector_distance(self, col, param) -> str: ...  # 向量距离：PG 是 <=>，Oracle 是 VECTOR_DISTANCE
    @abstractmethod
    def text_search_score(self, col, query_param, *, index_name=None) -> str: ...
    @abstractmethod
    def upsert(self, table, columns, conflict_columns, update_columns) -> str: ...
    @abstractmethod
    def bulk_unnest(self, param_types) -> str: ...  # 批量 unnest 展开
    @abstractmethod
    def advisory_lock(self, id_param) -> str: ...   # pg_try_advisory_lock 咨询锁

# engine/sql/postgresql.py
def build_semantic_arm(
    self, *,
    table: str,              # 表名
    cols: str,               # 要 SELECT 的列
    fact_type: str,          # observation / world / experience
    embedding_param: str,    # $1 查询向量
    bank_id_param: str,      # $2 bank 过滤
    fetch_limit: int,        # 拉取上限（HNSW 近似，实际 5x over-fetch）
    min_similarity: float,   # 最低相似度阈值 0.3
    tags_clause: str = "",   # 标签过滤（可选）
    groups_clause: str = "", # 标签组过滤（可选）
    extra_where: str = "",   # 扩展条件（时间过滤等）
) -> str:
    return (
        f"(SELECT {cols},"
        f"        1 - (embedding <=> {embedding_param}::vector) AS similarity,"
        f"        NULL::float AS bm25_score,"
        f"        'semantic' AS source"
        f" FROM {table}"
        f" WHERE bank_id = {bank_id_param}"
        f"   AND fact_type = '{fact_type}'"
        f"   AND embedding IS NOT NULL"
        f"   AND (1 - (embedding <=> {embedding_param}::vector)) >= {min_similarity}"
        f"   {tags_clause}{groups_clause}{extra_where}"
        f" ORDER BY embedding <=> {embedding_param}::vector"
        f" LIMIT {fetch_limit})"
    )

# engine/sql/postgresql.py（BM25 分支节选）
if text_search_extension == "vchord":
    # <&> 返回 NEGATIVE BM25 分数（越小越相关），取负转正
    bm25_score_expr = f"-(search_vector <&> to_bm25query('idx_memory_units_text_search', tokenize({text_param}, 'llmlingua2')))"
    bm25_order_by = f"{bm25_score_expr} DESC"
    # VectorChord 对每个文档都打分，不像 tsvector 有布尔 @@ 门槛，
    # 必须用 score > min 过滤，否则 LIMIT 会用零分不相关行填满
    bm25_where_filter = f"AND {bm25_score_expr} > {bm25_min_score:g}"
elif text_search_extension == "pgroonga":
    # &@~ 接受 pgroonga 查询语法；转义文本避免记忆内容里的 ">" "(" 被解析成查询
    bm25_score_expr = "pgroonga_score(tableoid, ctid)"
    bm25_where_filter = (
        f"AND (COALESCE(text,'') || ' ' || COALESCE(context,'') || ' ' || COALESCE(text_signals,'')) "
        f"&@~ pgroonga_query_escape({text_param})"
    )
elif text_search_extension == "pg_search":
    # ParadeDB：@@@ 需要字段限定查询，把 query 扇出到所有索引字段
    bm25_where_filter = (
        f"AND id @@@ paradedb.boolean(should => ARRAY["
        f"paradedb.match('text', {text_param}), "
        f"paradedb.match('context', {text_param}), "
        f"paradedb.match('text_signals', {text_param})])"
    )
else:  # native tsvector
    bm25_where_filter = f"AND search_vector @@ to_tsquery('{bm25_language}', {text_param})"

QueryAnalyzer (抽象基类)
├── DateparserQueryAnalyzer   → 规则优先，dateparser 兜底（200+ 语言）
└── TransformerQueryAnalyzer  → 规则优先，T5 小模型兜底（80M 参数）

# engine/query_analyzer.py
class DateparserQueryAnalyzer(QueryAnalyzer):
    def load(self) -> None:
        """Triggers the real initialization cost (regex tables, timezone data) at
        load time so the first actual recall doesn't pay the cold-start penalty."""
        if self._search_dates is None:
            from dateparser.search import search_dates
            self._search_dates = search_dates
            # Warm up: fire a dummy call to trigger lazy-loaded internal tables.
            self._search_dates("today")

    def analyze(self, query, reference_date=None) -> QueryAnalysis:
        ...
        # Check for period expressions first (these need special handling)
        period_result = self._extract_period(query_lower, reference_date)
        if period_result is not None:
            return QueryAnalysis(temporal_constraint=period_result)
        # Lazy load dateparser (only imports on first call, then cached)
        self.load()
        ...

# Last week patterns
if re.search(
    r"\b(last\s+week|la\s+semana\s+pasada|la\s+settimana\s+scorsa|la\s+semaine\s+derni[eè]re|letzte\s+woche)\b",
    query, re.IGNORECASE):
    start = reference_date - timedelta(days=reference_date.weekday() + 7)
    return constraint(start, start + timedelta(days=6))

# Wrap dateparser in a defensive try/except. dateparser has been
# observed to crash with internal errors (e.g., IndexError from
# locale.translate_search) on certain query inputs. A parser bug
# should not bring down the whole search/consolidation pipeline.
try:
    results = self._search_dates(query, settings=settings)
except Exception as e:
    logger.warning("dateparser raised %s on query (treating as no temporal constraint): %s", type(e).__name__, e)
    return QueryAnalysis(temporal_constraint=None)

# Filter out false positives (common words parsed as dates)
false_positives = {"do", "may", "march", "will", "can", "sat", "sun", "mon", "tue", "wed", "thu", "fri"}
valid_results = [(text, date) for text, date in results if text.lower() not in false_positives or len(text) > 3]

# 90%+ 情况规则搞定，模型只在冷门模式才加载
result = self._extract_with_rules(query, reference_date)
if result is not None:
    return QueryAnalysis(temporal_constraint=result)
# Fall back to T5 model for unusual patterns
self._load_model()

prompt = f"""Today is {reference_date.strftime("%Y-%m-%d")}. Extract date range or "none".

June 2024 = 2024-06-01 to 2024-06-30
yesterday = {yesterday.strftime("%Y-%m-%d")} to {yesterday.strftime("%Y-%m-%d")}
last Saturday = {last_saturday.strftime("%Y-%m-%d")} to {last_saturday.strftime("%Y-%m-%d")}
what is the weather = none
{query} ="""

上一篇（0.8.0 初版）          本篇（当前实例）
generate_query_embedding  84ms  ┐
parallel_retrieval       352ms  ├─ 语义 10ms + BM25 10ms + 图 23ms
  └─ temporal extraction 305ms  │   （预热后 dateparser ≈ 0）
rrf_merge                  2ms  ┘
reranking                  3ms      reranking 3ms
token_filtering            4ms      token_filtering 4ms
─────────────────────────────────────────────────
总计                     472ms      总计 150-270ms

取 semantic #1 → bm25 #1 → graph #1 → temporal #1
→ semantic #2 → bm25 #2 → graph #2 → temporal #2 → ...
（去重，直到全部排完）