#接口调用入门指南
本指南将介绍如何查看接口文档并调用接口。
调用 Data Agent API 时还需要提供符合许可证要求的 Origin 或 Referer。本文的 curl 示例使用 Referer，完整规则请参考 API 请求来源与许可证校验。
注：本指南预设使用者熟知API调用相关基础知识，如什么是GET/POST，curl的运用，SSE的概念等。
#查看接口文档
本网站右上角有一个 "API" 链接，点击即可查看所有接口的详细说明（包含请求参数、响应参数、示例代码等）。如果没找到对应接口的说明，请联系我们。
#调用接口示例
以 登录 -> 问答接口 为例，介绍如何调用接口。
首先在api文档中搜索“用户登录获取token”接口，找到其请求参数。
注：如果无法通过用户名、密码登录，也可以先使用管理员 API 密钥调用用户 Token 签发接口，具体查看本网站的JWT Token 生成。
获取token后，将token添加到问答接口的请求头中。然后找到“对指定 AI 员工发起或继续会话”接口，找到其请求参数。
接口默认按照SSE返回，客户端需要监听SSE事件流来接收服务端的响应。
请求示例（curl）：
curl 'http://localhost:13000/api/agent:chat' \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'Content-Type: application/json' \
-H 'x-spaces: default' \
--data-raw '{"messages":[{"role":"user","content":"今年销售额","agent":"nora"}]}'响应示例（SSE）：
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"我"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"来为您查询"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"今年的销售额"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"。\n\n"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"\n\n```tool-execution\n{\"id\":\"RhRStDPq5d57Bgv4nQ_ir\",\"title\":\"Data Query (Alisa)\",\"name\":\"yiask-askAlisa\",\"description\":\"参数: {\\\"question\\\":\\\"今年销售额\\\"}\",\"status\":\"loading\"}\n```\n\n"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"\n\n```tool-execution\n{\"id\":\"RhRStDPq5d57Bgv4nQ_ir\",\"title\":\"Data Query (Alisa)\",\"name\":\"yiask-askAlisa\",\"description\":\"参数: {\\\"question\\\":\\\"今年销售额\\\"}\",\"status\":\"loading\",\"content\":\"```data-visualizer\\nid: 353959196622848\\n标准化后的问题: 今年销售额\\n状态: executing\\n```\"}\n```\n\n"},"logprobs":null,"finish_reason":null}]} // 注意这里的data-visualizer id，后面会用到！
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"\n\n```tool-execution\n{\"id\":\"RhRStDPq5d57Bgv4nQ_ir\",\"title\":\"Data Query (Alisa)\",\"name\":\"yiask-askAlisa\",\"description\":\"参数: {\\\"question\\\":\\\"今年销售额\\\"}\",\"status\":\"success\",\"content\":\"```data-visualizer\\nid: 353959196622848\\n标准化后的问题: 今年销售额\\n数据查询范围: {\\\"日期\\\":{\\\"$offset\\\":{\\\"year\\\":0}}}\\n数据结果：\\n总金额: 475.81万\\n```\\n[INSTRUCTION: 基于以上查询结果，请提供简洁的总结分析（1-2句话概括核心洞察），不要用文字重复具体数字。如果用户只是要求展示图表，直接结束即可。]\"}\n```\n\n"},"logprobs":null,"finish_reason":null}]} // 注意这里的data-visualizer id，后面会用到！
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"今年"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"销售额"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"表现"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"稳健，整体规模达到"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{"content":"较高水平。"},"logprobs":null,"finish_reason":null}]}
data: {"id":"chatcmpl-1773804894750-uq8thm","object":"chat.completion.chunk","created":1773804894,"model":"nora","system_fingerprint":"fp_default_v1","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}
data: {"message_id":"LFQfmFA4z7H"}
data: [DONE]如果要获取数据卡片的右上角"debug"按钮点开后窗口中展示的详细数据，还需要根据agent:chat接口返回中的data-visualizer id来请求yiask_logicform_execution接口。请求示例：
url中的353976858640384是data-visualizer id，需要替换为实际的值。
curl 'http://localhost:13000/api/yiask_logicform_execution/353976858640384' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/admin/chat' \
-H 'Content-Type: application/json' \
-H 'x-spaces: default'返回示例：
{
"data": {
"createdAt": "2026-03-20T03:24:00.178Z",
"id": 354320206069760,
"logicform_result": {
"sqls": [
"SELECT '0' AS `_id`,sum(`dwd_sales_detail`.`amt`) AS `总金额` FROM (SELECT STR_TO_DATE(date, '%Y-%m-%d %H:%i:%s') AS `date`,`dwd_sales_detail`.`prod_id` AS `prod_id`,`dwd_sales_detail`.`shop_id` AS `shop_id`,`dwd_sales_detail`.`cnt` AS `cnt`,`dwd_sales_detail`.`amt` AS `amt` FROM `dwd_sales_detail`) AS `dwd_sales_detail` WHERE `dwd_sales_detail`.`date` >= '2025-01-01 00:00:00' AND `dwd_sales_detail`.`date` <= '2025-12-31 23:59:59'"
],
"normed": {
"preds": [
{
"name": "总金额",
"pred": "金额",
"operator": "$sum"
}
],
"query": {
"日期": {
"$gte": "2025-01-01 00:00:00",
"$lte": "2025-12-31 23:59:59",
"$options": {
"$offset": {
"year": -1
}
}
}
},
"schema": "dwd_sales_detail",
"defaultAuthQuery": {}
},
"result": [
{
"_id": "0",
"总金额": 52759531.3
}
],
"_status": "completed",
"logicform": {
"preds": [
{
"name": "总金额",
"pred": "金额",
"operator": "$sum"
}
],
"query": {
"日期": {
"$offset": {
"year": -1
}
}
},
"schema": "dwd_sales_detail",
"defaultAuthQuery": {}
},
"beforeEnrich": {
"preds": [
{
"name": "总金额",
"pred": "金额",
"operator": "$sum"
}
],
"query": {
"日期": {
"$offset": {
"year": -1
}
}
},
"schema": "dwd_sales_detail"
},
"functionLogs": [],
"customFunctions": [],
"_executeDuration": 158,
"columnProperties": [
{
"id": "amt",
"ui": {
"formatter": "0,0.00A"
},
"_id": "总金额",
"sid": "86M0n9BQue4mPU9wMzjN6",
"sql": null,
"_sid": "86M0n9BQue4mPU9wMzjN6",
"auth": true,
"enum": null,
"from": "dwd_sales_detail",
"name": "总金额",
"sort": 5,
"syno": [
"总",
"共",
"总和",
"加总",
"求和",
"一共",
"总共",
"合计",
"总计",
"sum",
"之和",
"总额",
"總额",
"總",
"總和",
"加總",
"一共",
"總共",
"合計",
"總計"
],
"type": "currency",
"unit": null,
"level": null,
"stats": {},
"params": [
{
"name": "pred",
"required": true
}
],
"prompt": "啦啦啦",
"can_ask": true,
"is_name": false,
"pattern": null,
"is_count": null,
"schemaID": "dwd_sales_detail",
"createdAt": "2026-01-29T00:10:03.952Z",
"formatter": null,
"spaceName": "default",
"updatedAt": "2026-03-20T02:58:07.057Z",
"field_type": "metric",
"returnType": "value",
"can_use_cte": true,
"constraints": {
"enum": null
},
"createdById": 1,
"description": null,
"is_additive": true,
"primal_type": "number",
"updatedById": 1,
"baseProperty": {
"id": "amt",
"ui": {
"formatter": null
},
"_id": "amt",
"sid": "86M0n9BQue4mPU9wMzjN6",
"sql": null,
"_sid": "86M0n9BQue4mPU9wMzjN6",
"enum": null,
"from": "dwd_sales_detail",
"name": "金额",
"sort": 5,
"syno": null,
"type": "currency",
"unit": null,
"level": null,
"stats": {},
"prompt": "啦啦啦",
"can_ask": true,
"is_name": false,
"pattern": null,
"is_count": null,
"schemaID": "dwd_sales_detail",
"createdAt": "2026-01-29T00:10:03.952Z",
"formatter": null,
"spaceName": "default",
"updatedAt": "2026-03-20T02:58:07.057Z",
"field_type": "metric",
"constraints": {
"enum": null
},
"createdById": 1,
"description": null,
"is_additive": true,
"primal_type": "number",
"updatedById": 1,
"is_analyzable": false,
"is_comparable": true,
"formatter_type": null,
"hierarchy_down": null,
"is_observation": null,
"is_projection_for": null
},
"is_analyzable": false,
"is_comparable": true,
"formatter_type": null,
"hierarchy_down": null,
"is_observation": null,
"is_projection_for": null
}
],
"wordSegmentation": [
{
"n": "去年",
"t": "val",
"_pos": 1,
"norm": "去年",
"value": "{\"$offset\":{\"year\":-1}}"
},
{
"f": null,
"n": "销售",
"s": "dwd_sales_detail",
"t": "schema",
"_pos": 2,
"norm": "销售明细"
},
{
"f": null,
"n": "额",
"s": "dwd_sales_detail",
"t": "pred",
"_pos": 3,
"norm": "金额"
}
],
"_alisaAskDuration": 81
},
"success": true,
"createdById": 1,
"spaceName": "default"
}
}#logicform_result 字段说明
| 一级字段 | 二级字段 | 类型 | 说明 |
|---|---|---|---|
| sqls | - | string[] | 生成的 SQL 查询语句数组 |
| beforeEnrich | - | object | 执行特殊业务规则前，纯从问题而生成的 logicform |
| logicform | - | object | 加上特殊业务规则后的 logicform |
| normed | - | object | 标准化后的 logicform，比较适合做程序判断，也是最后生成SQL时候的logicform |
preds | array | 指标定义，含 name（显示名）、pred（字段名）、operator（操作符如 $sum） | |
query | object | 查询筛选条件 | |
schema | string | 数据模型/表名 | |
defaultAuthQuery | object | 默认权限查询条件 | |
| result | - | array | 查询返回的数据结果 |
| _status | - | string | 执行状态（如 "completed"） |
| functionLogs | - | array | 自定义函数执行日志 |
| customFunctions | - | array | 涉及的自定义函数列表 |
| _executeDuration | - | number | 执行耗时（毫秒） |
| columnProperties | - | array | 结果列的属性定义 |
id | string | 列 ID | |
ui | object | UI 配置（formatter 格式化规则等） | |
_id | string | 列显示名称 | |
sid | string | 唯一标识符 | |
auth | boolean | 是否有权限访问 | |
name | string | 列名称 | |
type | string | 数据类型（currency/number/string 等） | |
syno | string[] | 同义词数组 | |
prompt | string | AI 分析提示词 | |
is_analyzable | boolean | 是否可深度分析 | |
is_comparable | boolean | 是否可比较 | |
is_additive | boolean | 是否可累加 | |
baseProperty | object | 基础属性引用 | |
| wordSegmentation | - | array | 分词结果（自然语言→归一化映射） |
n | string | 原始词 | |
t | string | 词类型（val/schema/pred） | |
norm | string | 归一化后的词 | |
value | string | 条件值（JSON 字符串） | |
| _alisaAskDuration | - | number | Alisa 请求耗时（毫秒） |
| schemas | - | object | 数据模型 schema 定义 |
Info
如使用api获取数据，前端图表渲染逻辑需要自行开发，可以通过logicform来判断提问意图。 数据在result字段。