Cube Cloud AI API 实用指南：用自然语言快速查询多维数据集

一. Cube AI API 上线概览

Cube 的 AI（人工智能）API 已正式上线，可在所有 Cube Cloud 付费层（包括 Starter）中使用。通过这一原生 API，Cube 为用户提供理想架构，扩展 Cube Cloud 的投资价值，并支持与 Anthropic Claude 模型或 BYO-LLM 集成，实现快速开发自然语言功能。

本文将介绍如何使用 Cube AI API 构建自然语言查询和多维数据集分析功能。

二. 为什么选择语义层？

语义层是实现 LLM（大型语言模型）可靠访问数据的基础。通过 Cube AI API，用户可以将 Cube 的通用语义层与 AI 功能结合使用。该 API 通过 REST 接口请求所需数据，而无需直接生成原始 SQL。

语义层充当 LLM 和数据之间的中间件，能够有效减少生成原始 SQL 时可能出现的错误或幻觉。其对象（如实体、维度和度量）相当于语言中的名词、形容词和量化描述，LLM 可基于这些定义回答问题，而不依赖其训练数据的全部知识。

此外，语义层还充当查询数据的特殊知识图，通过受约束的 API 输入，减少技术性错误。最终，Cube 会将请求编译为高效的原始 SQL，利用其强大编译器完成连接、聚合和过滤操作。

三. 为生成式 AI 准备多维数据集数据模型

在使用 Cube AI API 时，现有的 Cube Cloud 视图可直接使用，但可能需要一些优化。以下是最佳实践：

1. 使用清晰、标准的名称

字段名称应通俗易懂。例如，将“客户”命名为“Customer”，避免使用内部缩写如“CustAcctNm”。

2. 添加详细描述

为每个字段提供清晰描述，可通过元标签添加同义词、缩写或特定值的含义供 AI API 使用。

3. 确保成员名称唯一

类似字段应明确用途，例如，“order_timestamp”表示订单发出时间，“shipped_timestamp”表示订单发货时间。

通过这些优化，即使是外部数据工程师也能快速理解数据模型，确保其适用于 AI API。

四. 使用 Postman 测试 AI API

完成视图构建并启用 Cube AI API 后，可使用 Postman 测试 API 请求：

打开 Postman，点击“导入”或按 Command+O。

粘贴以下示例请求：

-H "Content-Type: application/json" \
-H "Authorization: Bearer EXAMPLE-API-TOKEN" \
--data '{
   "messages": [
       {
           "role": "user",
           "content": "我们在哪些城市的销售额最高？"
       }
   ]
}' \
https://YOUR_CUBE_API/cubejs-api/v1/ai/query/completions

将 YOUR_CUBE_API 替换为您的 Cube Cloud API 地址，EXAMPLE-API-TOKEN 替换为有效的 JWT 令牌。
修改请求正文中的问题，使其与您的数据集和视图相关。
点击“运行”，查看响应结果。

响应将返回由 AI 生成的多维数据集查询。您可以将查询复制到 Cube REST API 加载端点运行，或在请求主体中添加 "runQuery": true 直接执行查询。

例如，询问“销售额最高的城市”时，API 将返回按城市分列的总金额查询结果，并按降序显示前 10 位。

五. 总结

Cube Cloud AI API 为嵌入式开发人员和数据工程师提供简化的生成式 AI 开发工具。通过自然语言交互，降低了用户使用门槛。无论是构建 AI 代理还是聊天机器人，Cube AI API 都能帮助快速实现目标，节省时间和成本。

原文链接: https://cube.dev/blog/a-practical-guide-to-getting-started-with-cubes-ai-api