接口调用入门指南

本指南将介绍如何查看接口文档并调用接口。

注：本指南预设使用者熟知API调用相关基础知识，如什么是GET/POST，curl的运用，SSE的概念等。

查看接口文档

本网站右上角有一个 "API" 链接，点击即可查看所有接口的详细说明（包含请求参数、响应参数、示例代码等）。如果没找到对应接口的说明，请联系我们。

调用接口示例

以登录 -> 问答接口为例，介绍如何调用接口。

首先在api文档中搜索“用户登录获取token”接口，找到其请求参数。

alt text

注：如果无法通过用户名、密码登录，也可以先使用管理员 API 密钥调用用户 Token 签发接口，具体查看本网站的JWT Token 生成。

获取token后，将token添加到问答接口的请求头中。然后找到“对指定 AI 员工发起或继续会话”接口，找到其请求参数。

alt text

接口默认按照SSE返回，客户端需要监听SSE事件流来接收服务端的响应。

请求示例（curl）：

curl 'http://localhost:13000/api/agent:chat' \
  -H 'Accept: text/event-stream' \
  -H 'Authorization: Bearer <token>' \
  -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字段。

#接口调用入门指南

#查看接口文档

#调用接口示例

#logicform_result 字段说明

接口调用入门指南

查看接口文档

调用接口示例

logicform_result 字段说明