我想要通过 api 的方式使用 polardb 的 nl2bi 能力，请问哪里有使用文档？

要通过API的方式使用PolarDB的NL2BI（自然语言到SQL，NL2SQL）能力，您可以参考以下步骤和文档说明：

1. NL2BI 能力概述

PolarDB 提供了基于大模型的 NL2SQL 功能，允许用户通过自然语言查询数据库，并自动生成对应的 SQL 查询语句。这种功能特别适用于需要快速生成复杂 SQL 查询的场景。

2. 使用 NL2BI 的前提条件

在使用 NL2BI 功能之前，请确保以下条件已满足： - 您已经创建了表结构索引（schema_index），这是 NL2SQL 模型运行的基础。 - 您已具备访问 PolarDB API 的权限，并了解如何构造签名请求以确保安全性。

3. 创建表结构索引

在使用 NL2BI 功能前，您需要先为数据库中的表创建向量化索引。可以通过以下 SQL 语句完成：

/*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_text2vec, SELECT '') WITH (mode='async', resource='schema') INTO schema_index;

执行后，您将获得一个后台任务的 task_id。可以通过以下语句查询任务状态：

/*polar4ai*/SHOW TASK `bce632ea-97e9-11ee-bdd2-492f4dfe0918`;

当返回的 taskStatus 为 finish 时，表示索引构建已完成。

4. 调用 NL2SQL 模型

完成索引创建后，您可以使用以下 SQL 语句调用 NL2SQL 模型，将自然语言问题转换为 SQL 查询：

/*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, select '这一周的总收入有多少') WITH (basic_index_name='schema_index');

上述示例中，用户提出的问题是“这一周的总收入有多少”，系统会根据 schema_index 自动生成对应的 SQL 查询语句。

5. 典型问题示例

以下是一些典型问题及其对应的 NL2SQL 返回值： - 问题: 每个门店收入情况排序
返回值:

SELECT restaurant_id, SUM(actural_amount) AS total_income FROM bill_info GROUP BY restaurant_id ORDER BY total_income DESC;

• 问题: 在上海哪家门店收入最高
  返回值:

  SELECT b.restaurant_id FROM restaurant_info r JOIN bill_info b ON r.id = b.restaurant_id WHERE r.position LIKE '%上海%' GROUP BY r.position ORDER BY SUM(b.actural_amount) DESC LIMIT 1;
  

• 问题: 上海平均每个人消费多少
  返回值:

  SELECT AVG(bill_info.actural_amount / bill_info.diner_count) AS average_consumption_per_person FROM bill_info WHERE bill_info.restaurant_id IN (SELECT id FROM restaurant_info WHERE position = '上海');
  

6. API 文档查看路径

如果您需要更详细的 API 使用文档，可以通过以下路径获取： 1. 访问阿里云官方文档页面。 2. 在文档列表中找到 PolarDB 相关文档。 3. 单击提供的链接，进入 PolarDB API 文档页面。

此外，您还可以参考 PolarDB-X 1.0 的 API 文档，其中可能包含与 NL2BI 相关的接口说明： - 2017版本：访问 1.0（2017版本）的文档页面。 - 2019版本：访问 1.0（2019版本）的文档页面。

7. 注意事项

• 签名请求：在调用 API 时，请确保按照规范构造签名字符串，并正确计算签名值。具体步骤可参考《阿里云API调用与PolarDB请求签名指南》。
• 异步处理：部分操作（如索引创建）可能需要异步处理，请关注任务状态以确保操作完成。

通过以上步骤，您可以顺利使用 PolarDB 的 NL2BI 能力。如果需要进一步的帮助，请参考官方文档或联系技术支持团队。