官方AI助手接口使用指南

概述

本文档介绍如何使用官方提供的流式AI助手接口 https://luckycola.com.cn/aiTools/openAiAssistant。该接口支持流式响应，可以实时返回AI生成的内容，提供良好的用户体验。

温馨提示: 这篇文档主要介绍“AI助理接口”的详细使用,不介绍“AI助理组件(SuspendedBallChat)”的使用,如果需要理解“AI助理组件(SuspendedBallChat)”详细的使用请查看组件文档: [组件npm官方文档 (opens new window)](https://www.npmjs.com/package/ai-suspended-ball-chat)

接口信息

• 接口地址: POST https://luckycola.com.cn/aiTools/openAiAssistant
• 响应类型: 流式响应 (Server-Sent Events)
• 模型: qwen-turbo (通义千问)
• 支持功能: 文本对话、上下文记忆、搜索增强

请求参数

必要的请求参数 (JSON)

参数名	类型	必填	默认值	说明
appKey	string	是	-	应用密钥，前往LuckyCola官网[用户中心]获取(luckycola.com.cn)
systemPrompt	string	否	'你是一个智能助理,帮助用户回答各种问题'	自定义的系统提示词

AI助理组件配置使用案例

<template>
  <SuspendedBallChat
    :app-name="appName"
    :domain-name="domainName"
    :enable-streaming="true"
    :enable-context="true"
    :enable-local-storage="true"
    :callbacks="callbacks",
    url="https://luckycola.com.cn/aiTools/openAiAssistant"
    :custom-request-config="{
      headers: {
        'X-Custom-Header': 'custom-value',
      },
      customParams: {
        // 自定义的系统提示词
        systemPrompt: '你是一位精通各种编程语言的高级工程师,可以帮我用户解答各种编程问题.',
        // 官网(luckycola.com.cn)[用户中心]获取的AppKey
        appKey: '643d*********a'
      },
      requestParamProcessor: (baseParams, customParams) => {
        // ...
      }
      // ...组件其他详细配置请查看组件文档:https://www.npmjs.com/package/ai-suspended-ball-chat
  />
</template>

<script>
export default {
  data() {
    return {
      appName: 'my-assistant',
      domainName: 'user123',
      callbacks: {
        onUserMessage: (message) => {
          console.log('用户消息:', message);
        },
        onAssistantMessage: (message) => {
          console.log('AI回复:', message);
        },
        onError: (error) => {
          console.error('错误:', error);
        }
      }
    }
  }
}
</script>

响应格式

流式响应

接口返回 text/event-stream 格式的流式数据，每个数据块包含：

{
  "code": 0,
  "result": "AI回复的文本内容",
  "is_end": false
}

响应字段说明

字段名	类型	说明
code	number	状态码，0表示成功
result	string	AI回复的文本片段
is_end	boolean	是否为最后一条消息

完整响应示例

// 流式响应数据示例
{"code":0,"result":"人工","is_end":false}
{"code":0,"result":"智能","is_end":false}
{"code":0,"result":"是","is_end":false}
{"code":0,"result":"一门","is_end":false}
{"code":0,"result":"计算机科学","is_end":false}
{"code":0,"result":"的分支","is_end":true}

错误码说明

错误码	说明
-1	appKey无效或长度不足
-3	appKey无效或问题长度超限
-4	当前模型不支持图片输入
-9999	AI生成失败

使用限制

• 单次问题长度不超过5000字符
• 当前不支持图片输入功能
• 需要有效的appKey才能使用
• 如果没有appKey请前往luckycola官网(luckycola.com.cn (opens new window))=>[用户中心]获取
• 如果该接口无法满足您的业务需求您可以自行实现后端接口

自定义接口响应规范

如果您选择自行实现接口,您需要遵守以下的接口响应格式规范

流式响应格式（Server-Sent Events）

响应头设置：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Access-Control-Allow-Origin: *

数据格式： 每行返回一个JSON对象，以\n\n分隔

{"code": 0, "result": "Vue.js是一个用于构建", "is_end": false}
{"code": 0, "result": "用户界面的渐进式", "is_end": false}
{"code": 0, "result": "JavaScript框架。", "is_end": false}
{"code": 0, "result": "", "is_end": true}

字段说明：

字段	类型	说明
code	number	状态码，0表示成功
result	string	返回的文本内容片段
is_end	boolean	是否为最后一个数据块

完整流式响应示例：

// 流式响应数据示例
[
  {"code": 0, "result": "# Vue.js特点介绍\n\n", "is_end": false},
  {"code": 0, "result": "## 1. 渐进式框架\n", "is_end": false},
  {"code": 0, "result": "Vue.js采用渐进式设计，", "is_end": false},
  {"code": 0, "result": "可以逐步集成到现有项目中。\n\n", "is_end": false},
  {"code": 0, "result": "## 2. 响应式数据绑定\n", "is_end": false},
  {"code": 0, "result": "数据变化时自动更新DOM，", "is_end": false},
  {"code": 0, "result": "无需手动操作。\n\n", "is_end": false},
  {"code": 0, "result": "```javascript\n", "is_end": false},
  {"code": 0, "result": "// Vue响应式示例\n", "is_end": false},
  {"code": 0, "result": "data() {\n  return {\n", "is_end": false},
  {"code": 0, "result": "    message: 'Hello Vue!'\n", "is_end": false},
  {"code": 0, "result": "  }\n}\n```\n\n", "is_end": false},
  {"code": 0, "result": "以上就是Vue.js的主要特点。", "is_end": false},
  {"code": 0, "result": "", "is_end": true}
]

普通响应格式（JSON）

成功响应：

{
  "code": 0,
  "result": {
    "answer": "Vue.js是一个用于构建用户界面的渐进式JavaScript框架。它具有以下特点：\n\n1. **渐进式框架**：可以逐步采用\n2. **响应式数据绑定**：数据变化自动更新视图\n3. **组件化开发**：提高代码复用性\n4. **虚拟DOM**：提升性能\n5. **易学易用**：学习成本低"
  }
}

错误响应格式

错误响应统一格式：

{
  "code": 1,
  "message": "错误描述",
  "error": "详细错误信息"
}