Skip to content

architecture.md

Latest commit

 

History

History
114 lines (86 loc) · 6.43 KB

architecture.md

File metadata and controls

114 lines (86 loc) · 6.43 KB
Raw

JYDB Text2SQL 架构

目标边界

项目只维护 JYDB direct 主线：

strict YAML config
      |
JydbTaskDataset -> runner -> ReActAgent -> DirectTools
      |                         |              |
      |                         |              +-> schema_link
      |                         |              +-> peek_table
      |                         |              +-> query_mysql
      |                         |              +-> answer
      |                         |
      +-------------------------+-> trace.json / prediction.csv
                                            |
                                      Binary EX evaluator

控制状态

schema_mode 决定 schema_link 阶段模型看到什么，并控制起始流程：

  • none：不做 schema linking，controller 直接进入 schema_ready，模型面对原始库 schema（工程下界）。
  • hybrid：生产主线，schema_link 运行多级 recall pipeline（routing → BM25 → LLM 选表 → 规则注入 → 共现扩展 → 融合）产出候选表/列/关系边。
  • oracle：eval-only 上界实验。schema_link 内部 _apply_oracle_override 用 gold 表/列整体替换 linker 输出（ranked_tables/high_confidence_tables/candidate_columns 等被 gold 覆盖，置 oracle_schema: true），用于测"即便把正确 schema 喂给 agent，EX 是否仍低"。纯属泄露，禁止用于 train/prod run。

schema_mode=hybrid|oracle 时，controller 起始强制 schema_link；none 直接进入 schema_ready。之后模型可预览表、执行查询并提交。

workflow_state 只有：

start -> schema_ready -> query_ready -> done
   \          \             \-------> failed
    \----------\---------------------> failed

Controller 还负责模型错误重试、一次协议恢复、query/answer sibling 隔离、max steps 和 auto-answer。新 trace 的 control_state 只持久化 workflow_state。

DirectTools 是 controller 的唯一工具 interface，只暴露 json_schema()、 schema_snapshot()、execute() 和 tool_names()。工具集合在构造时固定，不存在动态 registry、 反射构造或 adapter 层。活动 controller 固定关闭 thinking，并在 max steps 后尝试 auto-answer。

工具职责

  • schema_link：唯一 hybrid 实现固定启用 column LLM 与 semantic recall，产生模型可见的 候选表列、关系边和 typed evidence。_typed_evidence.py 通过单一不可变请求对象封装 术语匹配、分组、置信度与有界排序，工具主流程不依赖这些内部规则。
  • peek_table：在当前 allowed set 中查看列含义与值格式，不消耗 data probe。
  • query_mysql：校验单条只读 SQL、allowed tables、probe budget 和行数上限，执行并缓存结果。
  • answer：提交显式表或缓存查询结果，校验矩形标量表并原子写入 prediction。

query_mysql 的公开参数只有 sql 与可选 max_rows。单次调用只允许一条语句；非查询根、写操作、session/admin 语句和锁定查询都被拒绝。每个任务有 mysql_probe_budget（默认 16）次数据查询探针上限；第 16 次返回 Probe budget reached (16/16 ...) 警告，预算耗尽后 runtime 可能额外放行一个启发式上像最终答案的查询。该历史高频失败机制见 output termination 报告。结果有硬行数上限（100,000 行）。

Session 与缓存

SchemaLinkSession 保留 allowed tables、候选列、关系边、typed evidence、glossary、query counters 和持久化。加载旧 session 时仅提取这些字段，多余历史控制字段被忽略。

MysqlResultCache 保存成功 data query。完全相同的 (SQL, max_rows) 由任务内 response cache 直接复用，不访问数据库、不增加 probe，也不重复写 answer history；失败与 introspection 不缓存。 answer(from_last_query=true) 优先选择最近的完整 final-shaped 候选；没有这种候选时回退到 最近完整结果。带 max_rows 的 partial sample 不可提交。

Memory 通过包内 ContextRenderer 构造模型可见历史。默认 context_deduplicated 保留 canonical schema snapshot，把历史 schema_link 响应替换为审计标记， 旧 query_mysql 行按既有总预算截断，且仅让最近两次成功 peek_table 保留最多三行样本。 表名、列注释、row count、warning/error 和原始 trace 均保留。历史实验配置显式保留旧模式。

Runner 与 artifact

  • 一任务、一 agent execution、一次结果落盘。
  • max_workers 只控制任务级并发。
  • 非零 timeout 使用子进程隔离。
  • Resume 只用于当前 direct artifact；历史复杂路线仅保证可读，不保证 resume。
artifacts/runs/<run_id>/
  run_metadata.json
  summary.json
  evaluation_report.json
  <task_id>/
    trace.json
    prediction.csv

Artifact metadata 固定写 "workflow": "direct"。Provenance v3 保存 Git、脱敏 config、manifest、schema、runtime 和 assets fingerprint；它证明运行边界，不证明结果正确。

兼容边界

Viewer 可容忍旧 trace 中额外的控制字段。历史适配不得进入 agent、runner、dataset 或活动工具。计划优先实现仅存在于 tag plan-first-final-20260728，恢复时从该 tag 建独立分支。

主要模块

职责 模块
Controller src/jydb_text2sql/agent/react_agent.py
Memory src/jydb_text2sql/agent/memory.py
Context rendering src/jydb_text2sql/agent/context_renderer.py
Direct tools src/jydb_text2sql/toolkit/registry.py
Schema linker implementation src/jydb_text2sql/schema_linker/
Typed column evidence src/jydb_text2sql/toolkit/tools/_typed_evidence.py
Link session src/jydb_text2sql/toolkit/schema_link_session.py
Database adapter src/jydb_text2sql/db_connector.py
SQL execution src/jydb_text2sql/toolkit/tools/query_mysql.py
Submission src/jydb_text2sql/toolkit/tools/answer.py
Runner src/jydb_text2sql/run/runner.py
Evaluator src/jydb_text2sql/evaluation/scoring.py

关键边界再强调

  • 只有一条 direct 主线：schema_link → peek_table/query_mysql → answer。旧 plan_first 路线冻结在 tag plan-first-final-20260728，恢复时从该 tag 建独立分支。
  • 日常入口是 README.md 与 DEVELOPMENT.md；历史交接记录见 archive。