Discussion: spring-ai-alibaba-studio design

[conghuhu]

spring-ai-alibaba-studio 设计

语雀文档实时更新：https://www.yuque.com/conghuhu/lb3478/nsgku3askwv74rua

本issue主要是关于 spring-ai-alibaba-studio的设计与分工

项目目标

开发目标：为spring-ai-alibaba 框架开发一个本地可用的调试和追踪工具。	工具形式：包括 CLI 和 Web UI 界面。	功能核心：可视化、调试、追踪 AI 应用的执行流程，尤其是chat client prompt chat model 等模块。

技术选型

前端：React+TS 用于构建响应式 UI。	cli：基于npm生态构建cli和发版。	后端：基于Java，在spring-ai-alibaba内部嵌入，符合社区生态。API定于遵循OpenAPI，以标准YAML交付。	可观测：OpenTelemetry 配合 Jaeger/Prometheus 等进行分布式追踪与性能分析。 同时支持导入/导出trace信息，便于工具历史数据的恢复。

系统架构设计

方案架构设计

模块划分

模块	模块描述
ChatClient	ChatClient是最核心的概念，且与ChatModel、Prompts、Tools等模块有耦合
ChatModel	模型，有chat、image、audio三种类型
Prompts	提示词，有user、system、Assistant、和Tool四种角色
Tools	工具，允许大型语言模型（LLM）在必要时调用一个或多个可用的工具，这些工具通常由开发者定义
文档检索	从大量未结构化或半结构化文档中快速找到与特定查询相关的文档或信息
Vetcor Store	开发向量存储部分的控制台
Trace	1. 基于Otel收集用户行为Trace信息 2. 可视化展示 3. 支持导出到本地。 本次赛题核心
模型评估	评估是一种测试形式，可帮助开发者验证 LLM 的回答并确保其满足质量标准。
终端交互（cli）	1. 基于Spring-ai-alibaba暴露的OpenAPI，将UI部分核心功能做成cli工具，参考kubetcl 2. 项目初始化，结合SpringBoot生态，帮助用户快速启动AI应用开发项目

Web UI 界面设计

前端目标

1. 轻量化，定位为开发调试工具，无需权限管理、加密等冗余功能
2. 可实现chatClient、models、tool等spring-ai-alibaba核心概念的可视化
3. 实现控制台调用大模型，支持普通响应和流式响应
4. 基于Otel生态，实现调用链路的可视化展示，且可查询历史输入和输出

Genkit界面图

Flows（类似ChatClient）

Stream效果，可以清晰看到模型stream响应的过程：

Result效果：

Prompts（提示词）

右侧template可以看到提示词模版，左侧可以看到实时的提示词效果。

并可以运行调试：

Models（模型）

右侧可以对模型参数调整，并运行查看效果。比如我问同样一个问题：“请帮我介绍下北京”，temperature分别设置0.4和1，效果如下：

**概述**

 Beijing 是中国的首都，位于中華人民共和國東北部，沿着渭河和大兴河 flows。它是世界上最大的城市，也是China 的政治、经济和文化中心。 Beijing 有一个丰富的历史， dating back thousands of years，它在古代曾经是中国的王国，在明清 dynastiesperiod下，是明、清两朝的都城。

**地理**

北京位于中國東北部，距離上海約 1,200公里。它有一个高山脈，称为 "山海關隱"，位于城市西邊。该区的平均海拔为60米，并且在降雨季节中常见的雨水是来自遼河。

**文化**

北京是中国最古老的城市之一，它拥有丰富的历史和文化。它的歷史可以追溯到公元前三百多年，是中国古代王国之一。 Beijing 的名胜地景包括：

*   **故宮**：这是一座古代宫殿，建于清朝，現在是世界上最大的古代宫殿。
*   ** Forbidden City**：这是皇帝的住所，建于 Ming dynasty，是中国历史上的一个重要地点。
*   ** Temple of Heaven**：这是天 emperor 的 Worship地，建于 Ming dynasty，是一个宗教和文化中心。

北京還有許多其他名胜地景，如：

*   **颛桥**
*   **神州门**
*   **长风 bridge**

**经济**

北京是中国的经济中心，也是国际商业和金融 hub。它有许多重要的公司和企业，例如：

*   **中国国务院**
*   **中国中央bank**
*   **中国人民銀行**

北京的经济也很强大，有一些重要的行业，如：

*   **技术行业**
*   **制造業**
*   **服务业**

北京是中国最大的城市，也是世界上第三大人口城市。它是中国的首都，位于中国中部。
地理位置
北京位于山海关的北部，毗邻天津和河北省。它的北面 bordered by 大北方山脉，南面 bordered by Yongdingyuan、延庆区、平谷区、怀柔县、密云县和香山区。
气候
北京有大地震带，地震频发，气候干燥。夏季高温，冬季低温。平均年降温为 -1.4℃。
历史
北京的历史可以追溯到公元前11世纪，作为北方诸国之一的 Yan国。后来它成为金朝、元朝和明朝的首都。清朝时期，它成为中国的首都，并且是整个地区的中心城市。
名胜景点
1. ** Forbidden City（紫禁城）**：世界上最大的石质建筑群。
2. 故宫博物馆：藏有大量文物和艺术品，包括明清-era皇帝的故宫。
3. 天安门广场：中国的国会大楼所在地，也是抗日战争和文化 Revolution的重要场所。
4. 颌山公园： Beijing最大的公园之一，被誉为“世界最美丽的公园”。
5. 清真寺：北京最著名的穆斯林宗教景点，是中国唯一以穆斯林为主要聚会场所的大型建造。
文化
北京有着丰富的文化生活，包括音乐、舞蹈、画展等。它也是中国的艺术中心之一，拥有多座艺术机构和博物馆。
旅游业
北京是中国最受欢迎的城市之一，是国内外游客的热门目的地。它的旅游业发展迅速，具有很高的经济价值。

Trace效果

界面原型图

主体框架&运行&ChatClients

右侧面板说明及设计：

• Model：显示该ChatClient的Model信息

• Prompt：显示该ChatClient的Prompt信息

• Tools：显示该ChatClient的Tools信息

TODO

运行&ChatModels&Chat Model

ChatModel有三种类型，Chat、Image、Audio，前端根据ChatModel实体类的modelType字段展示不同类型的样式。下面是纯文本对话模型：

运行&ChatModels&Image Model

下面是图片模型

运行&Prompts

运行&ChatModels&Audio Model

历史&Trace

评估

流程追踪与埋点

5.1 OpenTelemetry 埋点设计

为ChatClient流程中的关键节点进行埋点，追踪每个节点的执行情况。

埋点数据包括：

• 请求内容
• 响应内容
• 成功/失败状态
• 执行时间
• 耗时等

埋点可以通过 OpenTelemetry 库集成，对每个组件和步骤进行详细追踪。

5.2 追踪数据的存储与展示

使用 OpenTelemetry 的日志和追踪功能，将每次执行的详细信息记录下来。

可以存储在本地文件（优先支持）、数据库，或使用第三方服务（如 Jaeger 或 Zipkin）进行可视化。

Web UI 通过 REST API 或 WebSocket 实时展示流程的执行情况。

CLI 工具设计

6.1 基本功能

支持命令行操作，开发者可以通过 CLI 直接与spring-ai-alibaba 项目中的模块进行交互。

提供常用命令：

待补充。。。

6.2 CLI 技术栈

使用 nodejs 开发 CLI 工具，基于一系列命令与<font style="color:rgb(0, 0, 0);">spring-ai-alibaba</font> 的 OpenAPI 进行交互。

提供清晰的命令行帮助文档。

UI代码的使用

前端界面的demo，样式还需要优化，接口可以mock

接口mock的baseUrl，可以根据自己进行更换

框架自带的useRequest可以再抽离一层

项目开发

开发流程

1. 运行spring-ai-alibaba-examples下的cli-debug-example的CliDebugExampleApplication文件，可启动后端。注意需要配置好spring.ai.dashscope.api-key变量，可跳转 阿里云百炼平台 了解如何获取 API-KEY。
2. 进入spring-ai-alibaba-studio下的ui目录，运行<font style="color:rgb(53, 56, 65);">npm install</font>安装依赖，运行 <font style="color:rgb(53, 56, 65);">npm start</font>启动前端项目，浏览器打开<font style="color:rgb(53, 56, 65);">localhost:3333</font>即可访问控制台

OpenAPI接口

本项目完全遵循OpenAPI 3标准，产出标准的openAPI.yaml文件，可在Apifox、idea等软件中运行。

API文件位置：

人员分工

模块	模块描述	人力评估	人员分配
OpenAPI接口	完成整体的OpenAPI设计和规范	后端1	后端 @conghuhu
前端基础建设	整体UI选型、搭建、开发文档	前端2	前端 @SDUWYS、@jianyi-gronk
ChatClient、ChatModel	ChatClient是最核心的概念，且与ChatModel、Prompts、Tools等模块有耦合	后端1 前端1
Prompts、Tools	接口和控制台	后端1，前端1
文档检索、Vetcor Store	开发向量存储部分的控制台	后端1，前端1
Trace	基于Otel开发用户行为Trace信息，本次赛题关键	后端1，前端2
模型评估	评估是一种测试形式，可帮助开发者验证 LLM 的回答并确保其满足质量标准。	后端1，前端1
终端交互（cli）	1. 基于Spring-ai-alibaba暴露的OpenAPI，将UI部分核心功能做成cli工具，参考kubectl 2. 项目初始化，结合SpringBoot生态，帮助用户快速启动AI应用开发项目	1人，自由选型（go、nodejs均可）	@ev1lQuark

---