Cortex Analyst REST API¶

使用此 API 通过自然语言查询来回答有关数据的问题。

发送消息¶

POST /api/v2/cortex/analyst/message

使用请求中提供的语义模型或语义视图，为给定问题生成 SQL 查询。可以指定一个或多个模型；指定多个模型时，Cortex Analyst 选择最合适的模型。您可以进行多轮对话，在对话中可以基于之前问题提出后续问题。有关更多信息，请参阅 Cortex Analyst 中的多轮对话。

请求包括用户问题；而响应包括用户问题和分析师的回复。响应中的每条消息可以有多个不同类型的内容块。内容对象的 type 字段目前支持的三个值是：text、suggestions 和 sql。

响应可以在处理完成后立即发送，也可以在生成响应时逐步发送。

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅对服务器进行身份验证。
`Content-Type`	（必需）应用程序/json
`X-Snowflake-Authorization-Token-Type`	（可选）授权令牌类型。默认为 OAuth。有关更多信息，请参阅对服务器进行身份验证。

请求正文¶

在请求正文中：

将最后一个 messages[].role 字段设置为演讲者的角色，必须是 user。
在 content 对象中包含用户的问题。在此对象中：
- 将 type 设置为 text。
- 将 text 设置为用户的问题。
包含以下项之一：
- YAML 格式的语义模型规范。
- 包含语义模型规范的 YAML 文件路径。此文件必须处于暂存区中。
- 语义视图的名称。

下表描述了可在请求正文中设置的字段：

字段	描述
`messages[].role`	（必需）用于创建消息的实体的角色。目前仅支持 `user`。类型：string:enum 示例：`user`
`messages[].content[]`	（必需）作为消息一部分的内容对象。类型：对象示例： { "type": "text", "text": "Which company had the most revenue?" } Copy
`messages[].content[].type`	（必填）内容类型。目前仅支持 `text`。类型：string:enum 示例：`text`
`messages[].content[].text`	（必填）用户的问题。类型：字符串示例：`Which company had the most revenue?`
`semantic_model_file`	语义模型 YAML 文件的路径。必须是一个包括数据库和架构的完全限定的暂存区 URL。要指定多个语义模型，请使用 `semantic_models` 字段。如果您想改为直接在请求中提供 YAML 规范，请将 `semantic_model` 字段设置为语义模型的 YAML 规范。类型：字符串示例：`@my_db.my_schema.my_stage/my_semantic_model.yaml`
`semantic_model`	包含整个语义模型 YAML 的字符串。要指定多个语义模型，请改用 `semantic_models` 字段。如果您想改为指向文件中的 YAML 规范，请将文件上传到某个暂存区，并将 `semantic_model_file` 字段设置为文件的路径。类型：字符串
`semantic_models`	一个包含 JSON 对象的数组，其中每个对象都包含一个 `semantic_model_file` 或 `semantic_view` 字段。这些字段与顶级 `semantic_model_file` 和 `semantic_view` 字段具有相同的语义： `semantic_model_file` 指定存储在暂存区中、包含语义模型规范的 YAML 文件。（您不能使用此表单直接在请求中为语义模型指定 YAML。） `semantic_view` 指定语义视图的完全限定名称。例如： { /* ... / "semantic_models": [ {"semantic_view": "my_db.my_sch.my_sem_view_1" }, {"semantic_view": "my_db.my_sch.my_sem_view_2" } ] / ... */ } Copy 对于每个查询，Cortex Analyst 从列表中选择最合适的模型或视图。此功能简化了用户与 Cortex Analyst 的交互。您无需选择要查询的数据源，也不必跟踪要为每个数据源使用的语义模型或语义视图。只需在每个查询中指定所有模型或视图，然后让 Cortex Analyst 找出要使用的模型或视图即可。类型：数组小技巧 Cortex Analyst 不要求您指定多个模型或视图。如果您指定单一模型或视图，则该请求在功能上等同于包含顶级 `semantic_model_file` 或 `semantic_view` 字段的请求。为单模型请求使用 `semantic_models` 的优势在于，无论模型或视图数量是多少，您都可以使用相同的客户端代码。
`semantic_view`	语义视图的完全限定名称。例如： { /* ... / "semantic_view": "MY_DB.MY_SCHEMA.SEMANTIC_VIEW" / ... / } Copy 如果名称区分大小写或包含未加引号的标识符中不允许的字符，则必须将该名称置于使用反斜杠转义的双引号之间。例如，如果数据库名称、架构名称和视图名称包含连字符 (`my-database.my-schema.my-semantic-view`)： { / ... / "semantic_view": "\"my-database\".\"my-schema\".\"\"my-semantic-view\"\"" / ... */ } Copy 要指定多个语义视图，请使用 `semantic_models` 字段。类型：字符串
`stream`	（可选）如果设置为 `true`，则响应会在生成时通过服务器发送事件 (https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 流式传输到客户端（请参阅流式传输响应）。否则，在 Cortex Analyst 完全处理用户的问题后，返回完整的响应。类型：布尔

重要

您必须在请求正文中指定以下字段之一：

semantic_model_file
semantic_model
semantic_models
semantic_view

在暂存区上的文件中指定语义模型的示例¶

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        }
    ],
    "semantic_model_file": "@my_db.my_schema.my_stage/my_semantic_model.yaml"
}

Copy

指定语义视图的示例¶

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "which company had the most revenue?"
        }
      ]
    }
  ],
  "semantic_view": "MY_DB.MY_SCH.MY_SEMANTIC_VIEW"
}

Copy

非流式传输响应¶

此操作可以返回下面列出的响应代码。响应始终具有以下结构。目前，响应支持三种内容类型：text、suggestion 和 sql。内容类型 suggestion 和 sql 互斥，因此，如果响应包含 sql 内容类型，则不会包含 suggestion 内容类型，反之亦然。suggestion 内容类型仅在用户问题不明确且 Cortex Analyst 无法为查询返回 SQL 语句时才会包含在响应中。

当请求包含 semantic_models 字段时，响应会包含 semantic_model_selection 字段，指明为请求选择了哪种语义模型。

为确保向前兼容性，请确保实施考虑了内容类型并可处理类型。

代码	描述
200	语句已成功执行。响应正文包含一个消息对象，该对象包含以下字段： `message`：用户和分析师之间的对话消息。 :code:`message`（对象）：代表聊天中的消息。 `message.role` (string:enum)：生成消息的实体。`user` 或 `analyst` 之一。 :code:`message.content[]`（对象）：作为消息一部分的内容对象。 `message.content[].type` (string:enum)：消息的内容类型。`text`、`suggestion` 或 `sql` 中的一个。 message.content[].text`（字符串）：内容的文本。仅针对内容类型 ``text` 返回。 message.content[].statement`（字符串）：一条 SQL 语句。仅针对内容类型 ``sql` 返回。 message.content[].confidence`（对象）：包含与置信度相关的信息。仅对 ``sql` 内容类型返回。 message.content[].confidence.verified_query_used`（对象）：表示用于 SQL 响应生成的验证查询库中的验证查询。如果没有使用验证查询，则字段值为 ``null`。 :code:`message.content[].confidence.verified_query_used.name`（字符串）：从验证查询库中提取的验证查询的名称。 :code:`message.content[].confidence.verified_query_used.question`（字符串）：从验证查询库中提取的，验证查询回答的问题。 :code:`message.content[].confidence.verified_query_used.sql`（字符串）：从验证查询库中提取的，所用验证查询的 SQL 语句。 :code:`message.content[].confidence.verified_query_used.verified_at`（整型）：从验证查询库中提取的，验证查询时的时间戳数字表示。 :code:`message.content[].confidence.verified_query_used.verified_by`（字符串）：从验证查询库中提取的，验证查询的人。 message.content[].suggestions`（字符串）：如果无法生成 SQL，则语义模型可以为其生成 SQL 的问题列表。仅针对内容类型 ``suggestion` 返回。 `warnings`：分析师关于用户请求的警告列表。 :code:`warnings[].message`（字符串）：包含一个单独警告的详细描述。 :code:`response_metadata`（对象）：包含响应生成详情的元数据。 `response_metadata.model_names`：用于生成响应的模型列表。 :code:`response_metadata.cortex_search_retrieval`（对象）：使用 Cortex Search 解析的实体。 :code:`response_metadata.question_category`（字符串）：请求中的问题是如何分类的。

代码

描述

200

语句已成功执行。

响应正文包含一个消息对象，该对象包含以下字段：

message：用户和分析师之间的对话消息。
:code:`message`（对象）：代表聊天中的消息。
message.role (string:enum)：生成消息的实体。user 或 analyst 之一。
:code:`message.content[]`（对象）：作为消息一部分的内容对象。
message.content[].type (string:enum)：消息的内容类型。text、suggestion 或 sql 中的一个。
message.content[].text`（字符串）：内容的文本。仅针对内容类型 ``text` 返回。
message.content[].statement`（字符串）：一条 SQL 语句。仅针对内容类型 ``sql` 返回。
message.content[].confidence`（对象）：包含与置信度相关的信息。仅对 ``sql` 内容类型返回。
message.content[].confidence.verified_query_used`（对象）：表示用于 SQL 响应生成的验证查询库中的验证查询。如果没有使用验证查询，则字段值为 ``null`。
:code:`message.content[].confidence.verified_query_used.name`（字符串）：从验证查询库中提取的验证查询的名称。
:code:`message.content[].confidence.verified_query_used.question`（字符串）：从验证查询库中提取的，验证查询回答的问题。
:code:`message.content[].confidence.verified_query_used.sql`（字符串）：从验证查询库中提取的，所用验证查询的 SQL 语句。
:code:`message.content[].confidence.verified_query_used.verified_at`（整型）：从验证查询库中提取的，验证查询时的时间戳数字表示。
:code:`message.content[].confidence.verified_query_used.verified_by`（字符串）：从验证查询库中提取的，验证查询的人。
message.content[].suggestions`（字符串）：如果无法生成 SQL，则语义模型可以为其生成 SQL 的问题列表。仅针对内容类型 ``suggestion` 返回。
warnings：分析师关于用户请求的警告列表。
:code:`warnings[].message`（字符串）：包含一个单独警告的详细描述。
:code:`response_metadata`（对象）：包含响应生成详情的元数据。
response_metadata.model_names：用于生成响应的模型列表。
:code:`response_metadata.cortex_search_retrieval`（对象）：使用 Cortex Search 解析的实体。
:code:`response_metadata.question_category`（字符串）：请求中的问题是如何分类的。

默认情况下，在 Cortex Analyst 完全处理用户的问题后，立即返回完整的响应。有关流式传输模式响应的格式，请参阅流式传输响应。

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ],
    "response_metadata": {
        "model_names": [
            "claude-3-5-sonnet"
        ],
        "cortex_search_retrieval": [
            {
                "service": "my_db.my_schema.my_search_service",
                "response_body": {
                    "results": [
                        {
                            "CUST_NAME": "customer1"
                        }
                    ],
                    "request_id": "request1"
                },
                "query": "'customer1'"
            }
        ],
        "question_category": "CLEAR_SQL"
    }
}

Copy

流式传输响应¶

流式传输模式允许您的客户端在 Cortex Analyst 生成响应时即可接收响应，而不是等待整个响应生成。这提高了应用程序的感知响应能力，尤其是长时间运行的查询，因为用户可以更快地看到输出。流式传输响应还提供状态信息，可以帮助您了解在哪里 Cortex Analyst 正在生成响应和警告，帮助了解在 Cortex Analyst 未按预期工作时出现了什么问题。

要接收流式传输响应，请将请求正文中的 stream 字段设置为 true。流式传输响应使用服务器发送事件 (https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)。

Cortex Analyst 在流式传输响应中发送五种不同类型的事件：

status：传达有关 SQL 生成过程的状态更新。
message.content.delta：包含一段响应。此事件会多次发送。
error：表示 Cortex Analyst 遇到了错误，无法继续处理请求。不会发送更多 message.content.delta 事件。
warnings：包含处理过程中遇到的所有警告。警告不会导致处理停止。
response_metadata：在响应的末尾发送，显示有关请求处理的数据。
done：已发送，表示处理已完成，不会发送其他 message.content.delta 事件。

其中，message.content.delta 事件最需要理解，因为它们包含实际的响应内容。每个 delta 包含来自完整响应中某个字段的词元。每个 delta 事件可能包含单个字符到完整响应之间的任意字符，并且它们的长度可能不同。您在这些词元生成时即可收到它们；您可以自行将它们组合成最终的响应。

重要

来自不同响应（甚至是极其相似的响应）的事件可能会有所不同。不能保证活动将以相同的顺序或相同的内容发送。

简单示例¶

以下是简单查询的非流式传输响应示例：

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "This is how we interpreted your question and this is how the sql is generated"
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}

Copy

这是该响应可能发生的一系列流式传输事件（也可能一系列不同的事件）：

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "This is how we interpreted your question"
}

event: status
data: { status: "generating_sql" }

event: status
data: { status: "validating_sql" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " and this is how the sql is generated"
}

event: message.content.delta
data: {
  index: 1,
  type: "sql",
  statement_delta: "SELECT * FROM table"
}

event: status
data: { status: "done" }

使用 message.content.delta 响应中的 index 字段，确定该事件属于完整响应中的哪个字段。例如，这里前两个 delta 事件使用索引 0，这意味着它们属于非流式传输响应的 content 数组中的第一个字段（元素 0）。同样，包含 SQL 响应的 delta 事件使用索引 1。

带建议的示例¶

此示例包含针对模糊问题的建议问题。以下是非流式传输响应：

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "Your question is ambigous, here are some alternatives:"
            },
            {
                "type": "suggestions",
                "suggestions": [
                    "which company had the most revenue?",
                    "which company placed the most orders?"
                ]
            }
        ]
    }
}

Copy

以下是构成该响应的一系列可能的流式传输事件：

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "Your question is ambigous,"
}

event: status
data: { status: "generating_suggestions" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " here are some alternatives:"
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: "which company had",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: " the most revenue?",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: "which company placed",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: " the most orders?",
  }
}

event: status
data: { status: "done" }

在此示例中，非流式响应的 content 字段是一个数组。content 的元素之一是 suggestions 数组。因此，text 和 suggestions delta 事件的 index 字段的含义是指这两个不同数组中元素的位置。在组建完整响应时，您需要单独跟踪这些索引。

备注

当前，生成的 SQL 语句总是在单个事件中发送。将来可能不是这样。您的客户端必须做好在多个事件中收到 SQL 语句的准备。

其他示例¶

您可以在 Cortex Analyst GitHub 存储库 (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_streaming_demo.py) 中为 Cortex Analyst 找到 Streamlit 流式传输客户端。此演示必须在本地运行；目前 SiS 不支持流式传输。

请参阅 AI/ML Studio 中（在 Snowsight 中）的 Cortex Analyst Playground，了解流式传输响应的交互式演示。

流式传输事件架构¶

以下是流式传输响应中 Cortex Analyst 发送的事件的 OpenAPI/Swagger 架构。

status

message.content.delta

error

StreamingError:
type: object
properties:
  message:
    type: string
    description: A description of the error
  code:
    type: string
    description: The Snowflake error code categorizing the error
  request_id:
    type: string
    description: Unique request ID

Copy

warnings

Warnings:
type: object
description: Warnings found while processing the request
properties:
  warnings:
    type: array
    items:
      $ref: "#/components/schemas/Warning"
Warning:
type: object
title: The warning object
description: Represents a warning within a chat.
properties:
  message:
    type: string
    description: A human-readable message describing the warning

Copy

response_metadata

ResponseMetadata:
type: object
description: Details about request processing

Copy

发送反馈¶

POST /api/v2/cortex/analyst/feedback

提供定性最终用户反馈。在 Snowsight 中，反馈显示在 Monitoring 下方的 Semantic Model Admins 中。

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅对服务器进行身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶

字段	描述
`request_id`	（必填）您发送消息的请求 ID。在 `/api/v2/cortex/analyst/message` 的 `request_id` 字段中返回。有关更多信息，请参阅非流式传输响应。类型：字符串示例：`75d343ee-699c-483f-83a1-e314609fb563`
`positive`	（必填）反馈是积极的还是消极的。积极的或“点赞”为 `true`，消极的或“点踩”为 `false`。类型：布尔示例： `true`
`feedback_message`	（可选）用户的反馈消息。示例：`This is the best answer I've ever seen!`

字段

描述

request_id

（必填）您发送消息的请求 ID。在 /api/v2/cortex/analyst/message 的 request_id 字段中返回。有关更多信息，请参阅非流式传输响应。

类型：字符串

示例：75d343ee-699c-483f-83a1-e314609fb563

positive

（必填）反馈是积极的还是消极的。积极的或“点赞”为 true，消极的或“点踩”为 false。

类型：布尔

示例：

true

feedback_message

（可选）用户的反馈消息。

示例：This is the best answer I've ever seen!

响应¶

空响应正文，状态代码 200。

访问控制要求¶

有关所需权限的信息，请参阅访问控制要求。

有关如何对 API 进行身份验证的详细信息，请参阅使用 Snowflake 对 Snowflake REST APIs 进行身份验证。