> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Kaelio ktx 上下文引擎简明教程
- URL: https://www.hubwiz.com/blog/kaelio-ktx-context-engine-concise-tutorial/
- Published: 2026-06-03T13:55:42.000Z
- Updated: 2026-06-03T13:55:42.000Z
- Description: Kaelio ktx 是首批专门为应对这一挑战而构建的开源项目之一。它是一个自改进的上下文层，位于你的数据栈和你的代理之间，帮助它们按照团队认可的定义和业务规则查询数据。
- Author: admin
- Tags: LIBRARY, KAELIO KTX, #Import 2026-10-14 14:41

你刚刚给你的AI代理访问了你数据仓库的权限。你问了一个简单的问题：**"我们上个月的收入是多少？"**

代理运行了一个查询。返回了一个数字。你在周一站会上分享了这个数字。十分钟后，你的财务负责人找你：这个数字差了20%。

代理把退款订单算了进去。它查询了错误的表。它自己编造了一个连接。没有人同意过那个收入定义，但代理不知道。

这是当今数据团队中AI代理的一个隐性隐患。代理不笨，它是盲目的。它能看到你的schema。它看不到你们团队商定的定义、哪些连接是安全的、"活跃客户"意味着什么，或者`acct_tier_v2`列虽然还存在但已经过时了。

每次查询都从零开始，看似合理的SQL可能很快变成错误的SQL。输出看起来是正确的。查询运行没有错误。它只是使用了错误的连接、过滤器或指标逻辑，直到有人去核对数字，否则没有任何东西告诉你有问题。

随着AI代理成为组织使用数据的方式中越来越重要的一部分，**数据访问和数据理解之间的差距正变得越来越明显**。仅仅拥有数据访问权限已经不够了。代理还需要访问元数据、业务上下文和赋予数据含义的语义定义。随着AI原生系统成为现代数据平台的主要消费者，对专用上下文层的需求正变得越来越重要。

ktx 是首批专门为应对这一挑战而构建的开源项目之一。它是一个自改进的上下文层，位于你的数据栈和你的代理之间，帮助它们按照团队认可的定义和业务规则查询数据。

## 1、为什么数据代理需要的不只是一个数据库连接

AI代理正迅速成为现代数据栈的一部分。它们能回答问题、编写SQL、调查异常，甚至更新仪表板。但尽管能力很强，大多数代理对数据背后的业务上下文的理解仍然出人意料地有限。

一个典型的代理被赋予了访问数据仓库及其schema的权限。它能看到表、列、关系和数据类型。它看不到的是使这些表有意义的决策、定义和假设。

例如，代理通常不知道：

- 财务部门认为哪个收入指标是真实来源？
- 哪些连接是被批准的，哪些会产生扇出问题？
- `orders.amount`包含退款交易，除非被过滤
- 你的团队目前如何定义ARR、流失或活跃客户？
- 某个指标定义是否在六个月前发生了变化

这造成了一个根本性问题。代理可以访问数据，但无法访问数据背后的上下文。

结果是，每个任务都从零开始。代理探索schema，对要使用哪些表做出假设，并基于看起来合理的内容生成SQL。查询通常能成功运行并返回看似正确的结果。挑战在于"看似正确"并不总是意味着"正确"。

这就是语义层变得重要的地方。

语义层提供了一组共享的业务定义、指标、关系和规则，位于原始数据仓库之上。它不是每个用户或工具都不同地定义收入，而是每个人都使用相同的认可定义。

挑战在于，传统的语义层主要是为BI工具和仪表板设计的，而不是AI代理。它们擅长生成正确的SQL，但很少捕获代理同样需要的周围业务知识。

另一方面，组织通常在Notion、Confluence或内部wiki中维护文档。这些系统包含有价值的业务上下文，但它们不能验证连接、编译指标或生成可信的SQL。

ktx将两种方法结合成一个单一的上下文层。它提供可执行的语义定义以及可搜索的业务知识，使代理不仅能理解如何查询数据，还能理解如何正确解释它。

ktx不是强迫代理在每个任务中重新发现上下文，而是给它们一个经过审查和治理的起点，这个起点是基于你的团队已经创建的知识构建的。

## 2、什么是ktx？

ktx（context的缩写）是一个开源的、自改进的数据代理上下文层，由Kaelio构建，这是一家由Luca Martial和Andrey Avtomonov创立的Y Combinator支持的初创公司。除了开源项目，Kaelio还提供ktx Cloud（一个具有协作和治理功能的托管平台）和一个托管的数据代理（一个基于你的上下文层的生产就绪代理），为那些希望在自己的数据上获得可靠的AI而不需要自己构建基础设施的团队提供服务。

ktx教代理如何准确地查询你的数据仓库，从认可的指标定义、可连接列和它为你构建和维护的业务知识出发。

它通过在你的项目目录中维护两个提交的层来实现这一点：

1. `semantic-layer/*.yaml`：结构化的、可执行的定义：表、粒度、连接、度量、维度和过滤器。ktx编译器将这些转换为方言正确的SQL，所以代理永远不会从头重写规范查询。
2. `wiki/*.md`：自由格式的Markdown页面，包含业务定义、指标注意事项、报告策略和历史上下文。这些可以被代理搜索，可以被人类审查。

在幕后，ktx还维护支持文件，如源快照、搜索索引、溯源元数据和用于构建、搜索和演进上下文层的本地状态。

两个层都是普通文件，提交到Git中，可以像代码一样进行差异比较、合并和审查。

## 3、为什么选择ktx？

在亲手测试了ktx之后，以下四个方面值得强调：

### 3.1 它自动构建上下文

大多数语义层要求团队手动定义指标、连接和业务规则。ktx采取了不同的方法。

它连接到你现有的数据栈——数据仓库、dbt项目、BI工具和文档平台——并自动生成初始的语义层和业务wiki。

当你的数据栈发生变化时，再次运行`ktx ingest`会更新上下文层，同时保留团队已经审查和认可的定义。

### 3.2 上下文存储在Git中

ktx创建的一切都以普通文件存储在你的项目目录中。

这意味着你的语义定义和业务文档可以提交到Git中，在Pull Request中审查，随时间跟踪，并使用你团队已经用于代码的相同工作流来管理。

上下文不再存在于一个单独的平台中，而是成为你工程流程的一部分。

### 3.3 代理使用认可的定义

语义层不仅仅是文档。

代理可以搜索认可的指标和定义，然后将它们编译为SQL，而不是从头生成查询。这有助于确保它们使用你的团队已经商定的业务逻辑，减少错误连接、过滤器或指标计算的风险。

### 3.4 专为AI代理构建

ktx通过CLI和MCP服务器暴露其上下文，使其可以被Claude Code、Cursor、Codex、OpenCode和其他兼容MCP的客户端等现代AI助手访问。它还可以通过其MCP服务器集成到自定义的内部代理中——兼容任何支持MCP的框架，包括LangChain。ktx不是只给代理原始的数据库访问权限，而是提供了一种结构化的方式来发现业务定义、搜索上下文，并从认可的语义模型生成查询。ktx还支持多个AI提供商来构建和维护上下文层，包括Anthropic和Google Vertex AI。

## 4、ktx如何工作？

在高层面上，ktx分两个阶段工作：

### 第1阶段：构建上下文层

ktx首先从你的数据栈各处收集信息，包括你的数据仓库、dbt项目、BI工具和文档平台。

当你运行`ktx ingest`时，ktx分析这些源并构建一个由两个输出组成的上下文层：

**语义层**

语义层包含代理可以直接使用的结构化定义，包括指标、维度、连接、过滤器和数据集之间的关系。

**业务Wiki**

Wiki捕获不属于SQL的业务上下文，包括：

- 指标定义
- 报告策略
- 历史决策
- 业务规则
- 团队知识

这两个层结合起来，给代理既提供了对数据的技术理解，也提供了数据背后的业务上下文。

当你的数据栈发生变化时，ktx可以重新运行摄取过程，并提议更新上下文层，同时保留团队已经审查和认可的定义。

结果是一个版本控制的上下文层，人类和AI代理都可以使用。

### 第2阶段：使用上下文层来回答问题

一旦上下文层构建完成，代理就可以使用它来更可靠地回答问题。

代理不是立即生成SQL，而是首先寻找认可的业务定义和指标。

例如，如果用户问：

> 上个月的净收入是多少？

代理可以：

1. 在wiki中搜索收入定义和业务规则
2. 在语义层中搜索认可的收入指标
3. 将认可的指标编译为SQL
4. 对数据仓库执行查询

这种方法有助于确保答案遵循你的团队已经使用的业务逻辑，而不是依赖代理自己去推断正确的连接、过滤器和计算。

## 5、使用Orbit演示栈测试ktx

为了评估ktx，我在Kaelio公开的Orbit演示环境中测试了它，该环境包括一个PostgreSQL数据仓库、一个dbt项目、一个Metabase实例和一个Notion工作区。

数据集包含约**56个表中的38,000行数据**，大到足以模拟真实的SaaS分析环境，又小到便于测试。

开始使用很简单。安装CLI后：

```
npm install -g @kaelio/ktx

```

运行设置向导：

```
ktx setup

```

向导会引导你配置LLM提供商、嵌入模型、数据库连接和可选的上下文源（如dbt、Metabase和Notion）。配置完成后，ktx会自动执行首次摄取并创建项目结构。

设置完成后，我验证了安装：

```
ktx status

```

这显示了所有配置的连接、选择的LLM和嵌入提供商，以及生成的上下文层的摘要。

### 5.1 构建上下文层

要生成语义层和业务wiki，我运行了：

```
ktx ingest

```

完整的摄取过程在四个连接源上花费了约**27分钟**。

完成后，ktx报告语义搜索和代理上下文都已就绪。

### 5.2 探索结果

我首先测试的是语义搜索：

```
ktx sl "revenue"

```

结果显示了与收入相关的模型、受治理的指标和所有权信息。引起我注意的是，ktx不仅仅是列出表，它还识别出哪些指标被认为是权威的以及哪些团队拥有它们。

例如，`mart_revenue_daily`作为净收入的可信来源出现，带有两个从dbt拉取的特定标签：

- **受治理的指标：net\_revenue** 和
- **所有者：finance**。

这给了代理一个比仅仅暴露原始表强得多的起点；代理不仅找到了表，还识别了谁拥有该定义以及哪个指标是权威的。

接下来，我搜索了生成的wiki：

```
ktx wiki "subscription"

```

这是测试中最令人印象深刻的部分。

ktx不是生成技术性的schema文档，而是展示了实际的业务上下文：指标定义、报告策略、受治理的指标目录，甚至历史策略变更。

一个例子记录了一个激活指标定义的变更，该变更在特定日期生效。没有那个上下文，代理可能会根据分析的时期不同而返回不一致的激活数字。ktx使这些信息在任何SQL编写之前就可以被发现。

### 5.3 将指标编译为SQL

为了测试语义层，我将一个认可的收入指标编译为SQL：

ktx直接从认可的语义定义生成了SQL。

重要的是，代理没有自己发明指标逻辑。它编译了语义层中已有的经过审查的定义，确保与业务使用的定义保持一致。

### 5.4 测试代理工作流

最后，我将Claude Code连接到ktx MCP服务器，并测试了一个典型的工作流。

代理没有立即生成SQL，而是：

1. 在wiki中搜索业务上下文
2. 在语义层中搜索认可的指标
3. 编译认可的指标定义
4. 执行生成的SQL

这就是ktx与简单给代理数据库访问权限感觉根本不同的地方。代理不再猜测要使用哪些表、连接或过滤器。它从认可的业务定义出发，然后向外扩展。

对于涉及受治理的指标（如收入、ARR或激活）的问题，这种区别可能意味着一个看似合理的答案和一个正确答案之间的差异。

## 6、结束语

ktx通过构建和维护一个共享的上下文层来填补这一空白——一部分是用于可执行指标定义的语义层，一部分是用于业务知识的wiki——代理可以从中搜索和编译，而不是在每次查询时重新发明。

ktx不是你的数据仓库、dbt项目、BI平台或文档工具的替代品。相反，它充当一个上下文层，将它们汇聚在一起，并使这些知识可以被AI代理访问。

它是开源的，与你已经使用的工具集成，并通过CLI和MCP服务器暴露一切，你的代理可以原生使用。

有一点值得注意：上下文层只有在上下文存在的情况下才是强大的。ktx非常擅长发现和组织你的团队已知的信息，但如果指标定义、业务规则和文档还不存在，那是应该首先开始的地方。先建立知识，然后让ktx使其成为代理可用的。

在 [kaelio.com/start](http://kaelio.com/start?ref=hubwiz.com) 上使用Orbit演示栈尝试一下。你可以在一次`ktx setup`会话中从零开始构建一个代理就绪的上下文层。

---

原文链接：[Introduction to ktx: The Open-Source Context Layer for Data Agents](https://pipeline2insights.substack.com/p/ktx-the-open-source-context-layer-for-data-agents)

汇智网翻译整理，转载请标明出处