构建上下文增强 Agent：California Schools¶

本指南先介绍 Datus 如何对长期数据上下文建模，再通过 California Schools 教程把理念落到实处。你将构建知识库、让子代理使用这些上下文，并与基线 Agent 对比效果。

如果你已经了解相关理念，可以直接跳到第二部分——手把手教程。

第一部分 —— 理念¶

什么是上下文数据工程¶

上下文数据工程（Contextual Data Engineering） 是在 AI 时代重新定义数据系统构建、维护与使用方式的新范式。它不再仅仅交付静态的表和管道，而是专注于构建 可演化的上下文——一个智能、鲜活的数据层，将元数据、Reference SQL、语义模型与指标融为一体，既方便人工也方便 AI 智能体理解。

Data Engineering Pipeline Comparison

传统数据工程：数据管道以交付数据为终点。
上下文数据工程：管道本身演化为数据系统的知识图谱，持续吸收历史 SQL、反馈循环和人工修正。

这不只是“搬运数据、建表”，而是“理解并持续进化”围绕数据的上下文。

为什么重要¶

缺乏上下文的大模型会产生幻觉

数据上下文广阔且复杂。我们需要最懂数据的数据工程师来构建可复用、面向 AI 的上下文，为每一次查询和回答提供依据。

静态数据表无法满足动态需求

现代业务问题每天都在变化。临时分析请求占据了数据工程师一半的时间，而这些查询背后的知识很少被捕获或复用。

传统数据工程缺乏可演化能力

过去的关注点一直偏向数据消费者（分析与看板），而非构建上下文与准确性的生产端。上下文数据工程改变了这一点——让工程师输出“鲜活的上下文”，而非静态的工件。

为什么选择 Datus¶

上下文自动捕获

Datus 会按需捕获、存储并召回历史 SQL、数据表结构、指标与语义层，将每一次交互都转化为长期知识。

强化的长期记忆

双重召回机制（树结构 + 向量）不仅能记住精确匹配，还能识别语义相关的查询与模式，持续构建你的“上下文图谱”。

不断演进的上下文工程

系统从机器生成与人工反馈中学习，随时间迭代优化。每次纠错、基准测试或成功案例都会沉淀到自我进化的数据记忆中。

核心概念¶

长期记忆¶

我们将 数据工程上下文（长期记忆） 建模为 两棵树：

Context Tree Structure

在 Datus CLI 中，可以通过 /catalog 与 /subject 浏览和编辑
使用 /bootstrap 斜杠命令批量初始化并冷启动知识库
借助子代理（Subagent），你可以定义范围化上下文——从全局存储中挑选一个精心整理的子集，实现精准、具领域感知的交付

交互式上下文构建¶

协同创作的上下文

大模型从数据表和 Reference SQL 起草语义模型与指标，工程师负责完善标签、元数据和主题树。

命令驱动的迭代

直接描述要创建或更新的资产，主 agent 会自动委派给相应 subagent。单次明确指定可使用 @Agent semantic_modeling，连续操作可先使用 /agent semantic_modeling 选择当前 agent。

反馈驱动持续改进

通过 /chat 探索、成功案例回写、问题与基准循环，将使用过程转化为可复用的长期知识。

子代理系统¶

Subagent System

范围化、具领域感知的子代理

将描述、规则和上下文打包，统一管理特定业务场景所需的数据表、SQL 模式、指标与约束。

可配置的工具与 MCP

针对不同场景配置工具。内置工具包括数据库、上下文搜索与文件系统等，可按需启用与组合。

面向强化学习的架构

子代理的范围化上下文构成理想的强化学习环境（环境 + 问题 + SQL），便于持续训练与评估。

工具与组件¶

Datus CLI

专为数据工程师打造的交互式 CLI，内置上下文压缩与检索。直接输入自然语言问题，Datus 会自动派发给合适的 Agent。/datasource、/model 等斜杠命令用于管理会话；@Agent <name> 可将单次提问明确路由到某个子代理，/agent <name> 则会为后续对话选择当前子代理。在空输入行按 Tab，可以在自然语言、SQL 和 Bash 输入模式之间切换。

Datus Agent

一个基准测试与引导工具，作为 CLI 的批处理伙伴，可用于：

从历史数据构建初始上下文
运行基准测试与评估
暴露相应 API

Datus Chat

面向分析师与业务用户的轻量级网页聊天机器人，支持：

多轮对话
内置反馈（点赞、问题反馈、成功案例）

第二部分 —— 手把手教程：California Schools¶

本演练带你完成上述理念的五个落地结果——构建知识库、打包两个子代理、对比基线与上下文增强的回答效果——但每一步都由你亲自操作。完成后你将得到：

一个填充完整的知识库（元数据 / 指标 / Reference SQL）
两个工具集差异明显的子代理（datus_schools 与 datus_schools_context）
一份基线 vs. 上下文增强的基准测试结果可对比
一组多轮评估，直观展示上下文演化如何带来 SQL 准确率提升

前置条件¶

需要：

已安装 datus（参见快速开始）
在 datus 内通过 /model 配置好 LLM provider；选择器会把凭据写入 ~/.datus/conf/agent.yml
使用默认的 Dosi 语义层适配器；交互式启动且未配置语义适配器时，Datus 会自动安装，也可以通过 /services semantic 显式选择

不需要下载或手动 cp 任何文件。首次启动 datus 在没有配置时会自动 bootstrap ~/.datus/：

~/.datus/sample/ —— 内置样本数据（首次启动创建；后续启动将保留已有文件）
~/.datus/benchmark/california_schools/ —— 你的工作副本（升级时保留改动）
~/.datus/conf/agent.yml —— california_schools 数据源与基准已预写

所以执行一次 datus 之后，可以直接进入 /model 与 /bootstrap。

步骤 1 —— 打开 CLI 并配置模型¶

datus

在 REPL 中：

> /model

──── Model Selection ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   Providers   Plans   Custom    (Tab or ←/→ to switch)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  → claude  ✓  ← current
    deepseek  ✓
    gemini  ✓
    kimi  ✓
    openai  ✓
    glm  [needs setup]
    minimax  [needs setup]
    qwen  [needs setup]

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  ↑↓ navigate   Enter select   e edit credentials   Tab/←→ switch   Esc back   Ctrl+C cancel

/model 选择器列出支持的provider。选一个并填入api-key(设置了环境变量可以自动识别)。Datus 会把选择持久化到 ./.datus/config.yml（项目级），凭据写入 ~/.datus/conf/agent.yml。

步骤 2 —— 初始化元数据（Schema tab）¶

在 REPL 内：

> /bootstrap

──── Datus Bootstrap ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   Schema   SQL   Template   Semantic Modeling    (Tab or ←/→ to switch)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Schema
  Crawl the live database schema into the metadata RAG.
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

datasource:        california_schools
[ ]  overwrite  (Space to toggle — checked = overwrite, otherwise incremental)                                                                                                      ^

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  ↑↓/Tab next field   ←/→ switch tab   Ctrl+R run this tab   Esc cancel

按 Ctrl+R，预期输出：

⏺ 💬 Running bootstrap task: metadata                                                                                                                                                

⏺ 💬 Crawling schema from datasource california_schools (mode=overwrite)…                                                                                                            

⏺ 🔧 schema_crawl()
  └─ ✓

⏺ 💬 Schema crawl finished.                                                                                                                                                          

⏺ 💬 Bootstrap finished.

更多介绍见元数据管理。

步骤 3 —— 初始化 Dosi 语义模型和指标（Semantic Modeling tab）¶

切到 Semantic Modeling tab，填写：

datasource:        california_schools
success_story:     ~/.datus/benchmark/california_schools/success_story.csv
[*] overwrite

success_story.csv 是 (question, sql) 对的 CSV，Datus 会把它作为创作 Dosi dataset、relationship 和 metric 的证据。该文件随样本数据集一起发布，因此上面的路径可直接使用。此创作流程要求项目使用 Dosi semantic adapter。

按 Ctrl+R，预期输出：

⏺ 💬 Running bootstrap task: semantic_modeling
⏺ semantic_modeling(~/.datus/benchmark/california_schools/success_story.csv)
  ⎿  Dosi YAML validated and reconciled to the Knowledge Base
⏺ 💬 semantic_modeling bootstrap completed

Datus 会把通过校验的 Dosi YAML 写入项目的 subject/semantic_models/ 目录，并将语义对象和指标完整同步到 Knowledge Base。

步骤 4 —— 初始化 Reference SQL（SQL tab）¶

切到 SQL tab，填写：

datasource:   california_schools
sql_dir:      ~/.datus/benchmark/california_schools/reference_sql
pool_size:    3
subject_tree: california_schools/Continuation/Free_Rate,california_schools/Charter/Education_Location,california_schools/Charter-Fund/Phone,california_schools/SAT_Score/Average,california_schools/SAT_Score/Excellence_Rate,california_schools/FRPM_Enrollment/Rate,california_schools/Enrollment/Total
overwrite:    [x]

按 Ctrl+R，预期输出：

⏺ gen_sql_summary(/Users/liuyufei/.datus/benchmark/california_schools/reference_sql/california_schools_1.sql)
  ⎿  Done (2 tool uses · 19.4s)
⏺ 💬 gen_sql_summary (/Users/liuyufei/.datus/benchmark/california_schools/reference_sql/california_schools_1.sql):                                                                   


   SQL Summary: Continuation School Free Rate Bottom 3                                                                 

        🔍 Query Purpose                                                                                   

This query identifies the 3 lowest eligible free meal rates for students aged 5-17 enrolled in Continuation Schools, using data from the frpm table. 

......

⏺ 💬 Indexed 13 reference SQL item(s).                                                                                                                                               

⏺ 💬 Bootstrap finished.

Datus 会解析 sql_dir 下的每个 .sql 文件，生成自然语言摘要、抽取联接与过滤条件，并按主题树叶子建立索引。

更多介绍见 Reference SQL 文档。

步骤 5 —— 浏览所建内容¶

继续在 REPL：

/subject

主题树应已被指标和 SQL 摘要填充：

主题树结构

/catalog 用于查看表/列元数据。这两个页面是后续你（与 AI）浏览知识库的主要入口。

步骤 6 —— 创建两个子代理¶

打开 ~/.datus/conf/agent.yml，在 agent: 节点下追加以下两段：agentic_nodes（定义两个子代理）与 workflow（定义对应的编排管线）：

  agentic_nodes:
    datus_schools:
      system_prompt: datus_schools
      prompt_version: '1.0'
      prompt_language: en
      agent_description: ''
      tools: db_tools
      mcp: ''
      rules: []
    datus_schools_context:
      system_prompt: datus_schools_context
      prompt_version: '1.0'
      prompt_language: en
      agent_description: ''
      tools: context_search_tools, db_tools
      mcp: ''
      rules: []
  workflow:
    datus_schools:
    - datus_schools
    - execute_sql
    - output
    datus_schools_context:
    - datus_schools_context
    - execute_sql
    - output

两个子代理的关键差异是 context_search_tools —— 只有 datus_schools_context 能召回前面步骤 2–4 构建的指标与 Reference SQL。这正是下一步基准测试要量化的差异。

调用子代理¶

/agent 不带参数会打开 TUI（Enter 切换当前 agent）；带名字则把默认 agent 切到 <name>：

/agent datus_schools_context
What's the average SAT score by school type?

如果只想就单条提问临时路由到某个 subagent，使用 @Agent <name> 提示：

What's the average SAT score by school type? @Agent datus_schools_context

同样的子代理也可在 Datus-Chat 中使用。

步骤 7 —— 基准测试：基线 vs. 上下文增强¶

回到 shell，先跑基线：

datus-agent benchmark \
  --datasource california_schools \
  --benchmark california_schools \
  --workflow datus_schools

datus-agent eval \
  --datasource california_schools \
  --benchmark california_schools \
  --output_file schools1.txt

再跑上下文增强版：

datus-agent benchmark \
  --datasource california_schools \
  --benchmark california_schools \
  --workflow datus_schools_context

datus-agent eval \
  --datasource california_schools \
  --benchmark california_schools \
  --output_file schools2.txt

评估结果

对比 schools1.txt 和 schools2.txt。上下文增强子代理生成的 SQL 在语义上更准确、列幻觉更少、联接更合理——因为它能召回前面构建的 Reference SQL 模式与指标定义。

步骤 8 —— 多轮基准测试¶

这是上下文数据工程最具说服力的演示——通过多轮迭代让上下文继续演化：

datus-agent multi-round-benchmark \
  --config ~/.datus/conf/agent.yml \
  --datasource california_schools \
  --benchmark california_schools \
  --workflow datus_schools_context \
  --max_round 4 \
  --group_name context_tools

基准测试对比

左图为不带上下文工具（datus_schools）的准确率；右图为带上下文工具（datus_schools_context）的准确率。注意后者起点更高，且随轮数的提升曲线更陡。

总结¶

到这里，你已经完整跑通了 Datus 的端到端循环：

组件	你完成的事情
元数据 bootstrap	索引了 schema、列描述与采样行
语义模型 bootstrap	基于成功案例生成 Dosi 语义模型
指标 bootstrap	抽取业务指标并落入主题树
Reference SQL bootstrap	19 个 SQL 文件被摘要、连接、索引
子代理	两个工具集差异明显的范围化代理
基准测试	量化对比基线 vs. 上下文增强
多轮迭代	见证上下文演化推动准确率提升

同样的流程适用于你自己的领域——把 /bootstrap 指向你自己的成功案例和 SQL 目录，一小时内就能拥有一个真正可演化的知识库。

下一步¶

如果想体验其他场景，请返回选择上手路径。

知识库

探索包含元数据、指标与 Reference SQL 的上下文管理细节。

深入了解
工作流集成

将上下文融入自动化数据管道与编排系统。

探索工作流
CLI 上下文命令

通过实践掌握 CLI 上下文管理命令。

查看命令
配置

为智能体、命名空间与存储配置高级设置。

配置指南

构建上下文增强 Agent：California Schools¶

第一部分 —— 理念¶

什么是上下文数据工程¶

为什么重要¶

为什么选择 Datus¶

核心概念¶

长期记忆¶

交互式上下文构建¶

子代理系统¶

工具与组件¶

第二部分 —— 手把手教程：California Schools¶

前置条件¶

步骤 1 —— 打开 CLI 并配置模型¶

步骤 2 —— 初始化元数据（Schema tab）¶

步骤 3 —— 初始化 Dosi 语义模型和指标（Semantic Modeling tab）¶

步骤 4 —— 初始化 Reference SQL（SQL tab）¶

步骤 5 —— 浏览所建内容¶

步骤 6 —— 创建两个子代理¶

调用子代理¶

步骤 7 —— 基准测试：基线 vs. 上下文增强¶

步骤 8 —— 多轮基准测试¶

总结¶

下一步¶

相关资源¶