← → 翻页 · B 静态 · ESC 索引
TTD Architecture · Field Note
SS · 26.05.30 · 01 / 18
EXTERNAL TECHNICAL SOLUTION · AGENTIC BI

面向生产级 Agentic BI 的
系统设计方案

这套方案解决的不是“模型会不会写 SQL”，而是企业级 BI 系统如何在治理、安全、可演进前提下稳定交付自然语言分析能力。
SOURCE · docs/handbook/system-architecture · semantic-plane · semantic-query-planner
→ swipe / arrow keys
Core Thesis
02 / 18

从 demo 到生产，
关键不是更强的模型，
而是更强的系统边界。

TTD 的设计理念是“让模型处在系统中，而不是让系统长在模型上”。治理、规划、执行和状态管理先被工程化，生成只是最后一步。
因此这套方案能同时回答三件事: 为什么可用、为什么可控、为什么能持续演进。
TTD architecture abstract panorama
Global Architecture
03 / 18
一个无状态 runtime，
一个强状态内核。
方案的核心取舍是把 runtime 做轻，把 state 做重。前端、路由层与 agent runtime 都可以横向扩展，而共享状态、检索上下文和控制面规则都被压入同一套持久核心。
Runtime
Stateless

worker 可池化部署、滚动更新，不背负正确性状态。

Core
R+V+G+D

关系、向量、图与动态 few-shot 在一个状态核心统一协调。

Control
Governed

认证、路由、治理与 guardrails 共同形成可控执行边界。

Online vs Offline
04 / 18
Design Principle 01 · Decouple request path from governance path

把实时响应与治理发布拆成两条闭环。

ONLINE QUERY PATH
在线链路只服务低延迟与稳定交付
浏览器拿到 JWT 后进入 runtime pool；Supervisor 初始化状态，Router 负责路径选择，Guardrails 负责执行前最后一道风险闸门。
Online query path
Low latency
本地验签、本地状态装配、SSE 流式返回，缩短首字节时间。
High safety
PII、AST、term binding、EXPLAIN、cost 逐层收口。
Elastic scale
session affinity 只优化缓存，不承担正确性职责。
OFFLINE PUBLISHING
离线链路只服务语义治理与能力演进
YAML 是唯一事实源；CI 先做 schema、SQL、cross-ref、version 校验，发布后再由 semantic_plane agent 同步到状态核心，做到不停机演进。
Offline publishing path
Source of truth
Git 管理 table / metric / term / rule / context 等全部语义资产。
Quality gate
版本、引用、SQL 与 schema 一起进入发布闸门。
Hot evolution
后端导入 R+V+G，无需重启 runtime 即可吸收新知识。
Query Pipeline
05 / 18
Design Principle 02 · Put deterministic stages around generation

把生成包进可验证的五段式流水线。

01
Understand
先把用户问题结构化，而不是直接让模型开始写 SQL。
02
Retrieve
用多范式检索和 term binding，把候选空间变小、变准。
03
Plan
确定性规划器先给 join 路径和 rewrite，再让模型生成。
04
Guard
用策略、AST、EXPLAIN 和修复循环拦住高风险 SQL。
05
Deliver
执行后继续做解释、可视化和追问，形成完整分析体验。
关键创新不是“链条更长”，而是让每一段都承担单一职责。甚至当命中 SQL Cache 时，系统也知道该跳过哪里、保留哪里。
Search Stack
06 / 18
Search Design 01 · Hybrid retrieval is a staged system

检索不是一次向量召回，
而是三段式混合搜索栈。

STAGE 01
Query Understanding
先从原问题中抽取 `entities.terms`、`metric_candidates` 和 search terms，让后续检索带着目标结构进入，而不是把整句自然语言直接丢给向量索引。
INTENT · TERMS · METRICS
STAGE 02
Hybrid Recall
Engine R 精确词匹配、字典匹配、Engine V 向量召回、Engine D 动态 few-shot 并行工作，再把结果合并给 reranker。
R + R+ + V + D
STAGE 03
Constraint Feedback
Graph traversal、term binding、business rule injection 和 corrective retrieval 让搜索结果持续被治理反馈修正，直到 SQL 进入可执行边界。
GOVERNANCE · GUARDRAILS
Engine Latency
07 / 18
Search Design 02 · Four engines, four access patterns

四引擎不是平均分工，
而是按访问模式接力。

R · direct < 5ms
D · few-shot 10-30ms
V · vector 10-50ms
G · graph 10-100ms
R 负责精确 truth lookup，V 负责语义召回，G 负责路径和边界推理，D 负责高相似 few-shot 注入。Graph 阶段串行依赖上游 asset IDs，而动态 few-shot 只有在 `approved + similarity ≥ 0.95` 时才会生效。
Term Binding
08 / 18
Search Design 03 · Strong-route semantic binding

术语绑定，把“相似”升级成“必须”。

NAIVE SEMANTIC SEARCH
只有语义相似，没有物理约束
模型可能知道“价格”大概相关，却不知道它必须来自哪张表、哪一列，也不知道哪些相似表其实会造成错误 fanout。
RISK 01
同义词命中但落到错误父表。
RISK 02
Prompt 只能“建议”，无法强制列引用。
RISK 03
Guardrails 只能事后发现，不能前置提升正确候选。
TERM BINDING STRONG ROUTE
`term → mapped_asset_id → parent table`
一旦业务术语命中 `mapped_asset_id`，它会作为强约束穿过 reranker、prompt assembler、guardrails 与 corrective retrieval，变成端到端约束信号。
RERANKER
绑定列和父表加分，非绑定候选主动降权。
PROMPT
明确注入“必须使用 table.column”的约束文本。
GUARD + REPAIR
Layer 2d 拦截错误表引用，违规时 corrective retrieval 拉回正确资产。
Search Artifacts
09 / 18
Search Design 04 · Retrieval consumes structured knowledge

检索阶段真正消费的，
远不止向量。

01
Business Term
从业务词汇映射到表、列、指标，是搜索入口的第一层语义约束。
02
Alias Terms
列别名字典支撑 Engine R，弥补纯向量对字段俗称的遗漏。
03
Join Rule
告诉系统哪些 join 合法、基数如何、fanout 风险在哪里。
04
Few-shot
向量相似度与 grounded assets 共同选择 3-5 组示例注入生成。
05
Business Rule
高优先级规则会直接注入 guardrails，约束 SQL 的写法与解释。
06
Business Context
把数据集假设、市场边界、有效期与业务语境补全给运行时。
Fast Path & Repair
10 / 18
Search Design 05 · Performance and failure containment

把延迟与失败，
都收进明确的系统杠杆里。

0.92
SQL Cache Similarity
命中时直接跳到 guardrails，跳过检索和生成，仍保留安全校验。
15m
Cache TTL
缓存是性能优化而不是结果来源，短 TTL 限制陈旧 SQL 的风险暴露。
1
Repair Retry
SQL 执行失败后最多重试一次，修复 prompt 会带原 SQL、错误信息和白名单上下文。
3
Circuit Breaker
连续失败达到阈值即熔断，保护下游模型服务与用户体验。
24h
Metadata Cache TTL
元数据缓存让检索阶段少打数据库，但 ingest 完成后会主动 invalidate，保证知识热更新。
Observability Fabric
11 / 18
Operations 01 · Unified observability surface

把追踪、评分、事件流和日志，
压进同一个观测门面。

`ObservabilityFacade` 是请求链路的唯一入口。Agent、Memory、Evaluator 共享同一 `trace_id`，因此线上问题可以从用户请求一路追到 LLM 调用、记忆操作和最终评分。
这意味着观测体系不是附加看板，而是 runtime 里的第一等控制面: 每次请求都有 trace，每个关键步骤都有 span，每次评估和反馈都能回写 score。
Observability
Facade
Langfuse
Trace / span / score 统一挂载，直接关联评估结果与用户反馈。
AutoMQ
事件只发引用 ID，下游据此做审计、告警与仪表盘。
structlog
JSON logs 提供基础运行证据，便于收集、过滤与回放。
Trace-native Memory
七类 memory lifecycle events 同时写入 trace event 和 event stream。
one trace context across agent, memory, evaluator and feedback
Operational Confidence
12 / 18
Why Ops Matters

观测体系的终点，
不是看板，而是业务信心。

01 · Auditability
Auditability evidence chain
每次分析都有证据链
`trace_id`、`session_id`、event refs 和评分结果把一次请求的输入、生成、执行与反馈串成可审计记录。
02 · Replayability
Replayability timeline
故障和争议都能回放
span、JSON logs 和 memory lifecycle events 让团队能复盘一次错误回答到底偏在检索、规划、生成还是记忆写入。
03 · SLA-readiness
SLA readiness dashboard
把体验抽成可运营指标
有了 trace latency、success status、repair hit rate 和 evaluator scores，系统才能定义 p95、可用性和质量阈值。
04 · Accountability
Shared accountability
产品、治理、运维能共担结果
当反馈、评分和事件流进入同一观测面，问题不再只是“模型错了”，而是能被归因、分派、持续修正的系统责任。
Retrieval Quality Loop
13 / 18
Search Design 06 · Retrieval is evaluated, not assumed

检索不是召回结束，
而是进入质量闭环。

ASSET COVERAGE
至少命中一张表和一组关键列
`retrieval_evaluator` 先检查 table / column 命中数，不足时直接标记 issues，并触发 corrective retrieval。
≥1
RELEVANCE SCORE
平均相关性低于阈值就不进入下一步
系统要求检索结果的平均 relevance score ≥ 0.55，否则说明召回上下文不足以支撑 SQL 生成。
0.55
METRIC COVERAGE
期望指标必须完整召回
对 deep analysis 路径，系统会检查 metric coverage 是否达到 100% expected，再决定是否继续生成或回退修复。
100%
System Core
14 / 18
Innovation 01 · PG Supernode

把四种检索范式、
会话状态与控制锁压进同一内核。

这不是简单的数据库选型，而是一种系统简化策略: 用一套状态核心同时承接关系真相、向量检索、图推理、动态 few-shot 和记忆状态。
结果是连接池更少、跨组件一致性更强、故障面更集中，也更利于审计与回放。
PG Core
R
精确查询、结构化约束、source of truth。
V
语义召回、相似问题、asset discovery。
G
关系遍历、边界执行、图谱推理。
D
在线学习 few-shot，但必须经过审核与高阈值门控。
One stateful core for search, memory and coordination
Semantic Plane
15 / 18
Innovation 02 · Semantic Plane

把业务知识变成可发布、
可校验、可消费的语义控制面。

L1
Table Asset
表、列与安全策略定义分析可见范围。
L1
Metric Asset
指标口径、SQL 定义、默认维度与反例声明。
L1
Join Rule
基数、fanout 风险与 NL2SQL 可用性边界。
L1
Few-shot
正例、反例与澄清样例进入 in-context learning。
L1 + L2
Business Term
术语映射、同义词强度与 ambiguity matrix。
L2
Term Relationship
同义、冲突、替换与层级语义网络。
L3
Business Rule
约束 SQL 生成的业务规则与 anti-patterns。
L3
Business Context
背景假设、边界、有效市场与绑定规则。
8
这套设计把业务语义从 prompt 文本升级成发布系统: 所有资产要过 schema、cross-layer refs、SQL 和 version 闸门，运行时再以 R+V+G 的方式被直接消费。
Semantic Planner
16 / 18
Innovation 03 · Semantic Planner

先做确定性规划，
再做概率式生成。

Routing
KMB
Steiner tree 近似寻找最低代价 join 路径。
Rewrites
3
Join 消除、先聚合后关联、semi/anti join 推理。
Fallback
Safe
失败时返回空 guidance，主链路继续，不把 planner 变成单点。
Planner 位于 reranker 与 sql_generator 之间，不额外发起外部 I/O。它的价值不是替代模型，而是把最容易出错的 join 路径、扇出风险和语义改写提前确定下来。
Base 1.0
Fanout +2
High +5
Uncert +1.5
Cross +2
这就是“planner as advisor”的设计理念: 不直接编译 SQL，但用确定性算法把生成空间压缩到更安全、更高命中率的范围内。
Operational Laws
17 / 18
Design Philosophy

四条设计理念，支撑方案可用、可控、可演进。

01 · Governance First
Governance boundary gate
先定义边界，再开放生成
系统先回答“什么能问、什么能看、什么能算”，再把生成能力开放给用户。
02 · Async / Modular
Async modular lanes
把职责拆开，把延迟并行化
runtime、检索、规划、执行、解释各自独立演进，系统可以按链路局部优化而不必整体重写。
03 · Fail Safe
Fail safe guarded path
不确定时拒绝，不赌概率
planner 可失效、模型可降级、缓存可 miss，但高风险 SQL 不应带着不确定性直接穿透到数据面。
04 · Evolvable
Evolvable replaceable modules
知识与模型都要可热演进
语义资产、模型映射和数据面后端都能渐进替换，方案不会被单一模型或单一平台锁死。
18 / 18
CLOSING
MANIFESTO

Govern first.
Plan before generate.
Scale on a stateful core.

如果把这套方案压成一句话: 用系统设计吸收模型的不确定性，让自然语言分析从 demo 级能力变成企业级产品能力。
DOCS DISTILLED · THE TTD
2026.05.30
TAKEAWAYS
03 RULES
01

关键创新一: Semantic Plane 把业务知识变成发布系统

术语、规则、上下文和版本治理共同决定语义边界，运行时直接消费这些资产，而不是临时拼 prompt。

02

关键创新二: Semantic Planner 先规划再生成

KMB 路由、代数重写与 safe fallback，让复杂分析不必完全押注模型直觉，也不把 planner 变成单点。

03

关键创新三: Stateful Core + Guardrails 形成产品级下限

可以缓存、可以降级、可以换模型，但不能绕过持久状态、权限边界与执行前校验。这就是系统可信的底线。

→ END OF FIELD NOTE