AI服务代码说明文档

AI服务代码说明文档

目录结构介绍

AI_API
├── env.env                  # 环境变量配置文件（如API_KEY、AI_API_BASE_URL等）
├── package.json             # 项目依赖与脚本配置
├── package-lock.json        # 依赖锁定文件
├── pnpm-lock.yaml           # pnpm依赖锁定文件
├── src                      # 源码目录├── aiApi                # AI接口调用封装（如invokeAI函数）│   └── aiAPI.js├── config               # 配置文件目录（如端口、主机、API密钥等）│   └── config.js├── constants            # 常量定义（如返回码）│   └── resultConstants.js├── prompt               # 各AI服务的prompt模板及生成函数│   ├── dialogPrompt.js│   ├── generateQuestions.js│   ├── homeworkAnalysisPrompt.js│   ├── homeworkCorrection.js│   └── studyPathPrompt.js├── service              # 业务逻辑处理（每个AI服务的核心逻辑）│   ├── dialogService.js│   ├── generateQuesionsService.js│   ├── homeworkAnslysisService.js│   ├── homeworkCorrection.js│   └── studyPathService.js├── utils                # 工具函数（如请求模板、AI返回格式处理等）│   ├── requestTemplateUtils.js│   └── responseUtils.js└── main.js              # 服务主入口，路由与中间件注册

---

主要流程

1. 服务启动与路由注册
   src/main.js 是服务的主入口，基于 Koa 框架，注册了各类 AI 相关接口（如 /ai/dialog、/ai/studentHomeworkAnalysis 等），并统一使用 requestTemplateUtils.js 中的 handlePostRequest 和 handleGetRequest 进行请求处理，提升了代码复用性和一致性。

2. 请求处理与业务分发
   每个路由对应一个 service 层的函数（如 dialogService.js 的 getResponse），负责接收请求数据并处理主要业务逻辑。

3. Prompt 生成
   service 层会调用 prompt/ 目录下的 prompt 生成函数（如 toDialogPrompt、toGenerateQuestionsPrompt 等），根据业务需求和请求参数动态生成适合大模型的 prompt。

4. 大模型调用
   统一通过 aiApi/aiAPI.js 中的 invokeAI 函数调用大模型（如 OpenAI），将 prompt 发送给大模型并获取回复。

5. AI返回结果处理
   获取大模型返回后，service 层会调用 utils/responseUtils.js 中的 modifyAiResponse 对返回内容做统一格式处理（如去除无关标签、格式化输出等）。

6. 响应封装与返回
   处理后的结果通过 requestTemplateUtils.js 的模板函数统一封装为标准响应格式（包含 code、message、data），返回给前端或调用方。

代码文件介绍

src/main.js

src/main.js 是 AI 服务的主入口文件，负责初始化 Koa 应用、注册路由、配置中间件以及启动服务器。具体功能如下：

• 依赖引入：引入 Koa、koa-router、koa-bodyparser、koa-logger 等模块，以及从 config.js 中获取服务器配置（如 HOST、PORT）。
• 路由注册：通过 koa-router 注册多个 AI 相关接口，并统一使用 requestTemplateUtils.js 中的 handlePostRequest 和 handleGetRequest 处理请求，提升代码复用性。具体接口如下：
  • POST /ai/dialog：调用 dialogService.js 的 getResponse 函数，处理对话请求。
  • POST /ai/studentHomeworkAnalysis：调用 homeworkAnslysisService.js 的 studentHomeworkAnalysis 函数，处理学生个人作业分析请求。
  • POST /ai/homeworkAnalysis：调用 homeworkAnslysisService.js 的 teacherHomeworkAnalysis 函数，处理教师作业分析请求。
  • POST /ai/homeworkCorrection：调用 homeworkCorrection.js 的 getHomeworkCorrection 函数，处理作业批改请求。
  • GET /ai/generateQuestions：调用 generateQuesionsService.js 的 generateQuestions 函数，处理题目生成请求。
  • GET /ai/studyPath：调用 studyPathService.js 的 generateStudyPath 函数，处理学习路径生成请求。
• 中间件配置：使用 koa-logger 记录请求日志，使用 koa-bodyparser 解析请求体。
• 服务启动：调用 app.listen(PORT, HOST, ...) 启动服务器，并在控制台输出服务运行地址。

src/service/

src/service/ 目录下包含多个业务逻辑处理文件，每个文件对应一个 AI 服务的核心功能。具体如下：

• dialogService.js

  • getResponse(ctxBody): 接收请求体，调用 toDialogPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果，最终返回 {response: modifiedResponse}。

• homeworkAnslysisService.js

  • studentHomeworkAnalysis(ctxBody): 接收学生作业数据，调用 toStudentHomeworkAnalysisPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果，最终返回 {analysis: modifiedResponse}。
  • teacherHomeworkAnalysis(ctxBody): 接收教师作业数据，调用 toTeacherHomeworkAnalysisPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果，最终返回 {analysis: modifiedResponse}。

• homeworkCorrection.js

  • getHomeworkCorrection(ctxBody): 接收作业数据，调用 toStudentHomeworkCorrectionPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果。如果返回结果包含评分数组，则返回 {scores: JSON.parse(matches[0])}；否则，返回随机生成的评分数组。

• studyPathService.js

  • generateStudyPath(ctxQuery): 接收查询参数，调用 toStudyPathPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果。从返回结果中提取 JSON 内容，解析后返回学习路径对象。

• generateQuesionsService.js

  • generateQuestions(ctxQuery): 接收查询参数，调用 toGenerateQuestionsPrompt 生成 prompt，通过 invokeAI 调用大模型，并调用 modifyAiResponse 格式化返回结果，最终返回 {questions: JSON.parse(modifiedResponse)}。

src/prompt/

src/prompt/ 目录下包含多个 prompt 模板文件，每个文件负责生成特定 AI 服务的 prompt。具体如下：

• dialogPrompt.js

  • toDialogPrompt(question): 接收对话历史数组，将其转换为大模型所需的对话格式，并在最后一条用户消息前添加 prePrompt（要求返回 HTML 格式），最终返回对话历史数组。

• generateQuestions.js

  • toGenerateQuestionsPrompt(amount, label): 接收题目数量和标签，将 prePrompt（题目格式说明）与参数拼接，生成题目生成的 prompt。

• homeworkAnalysisPrompt.js

  • toStudentHomeworkAnalysisPrompt(studentHomework): 接收学生作业数据，将 studentHomeworkPrePrompt（学生作业分析模板）与数据拼接，生成学生作业分析的 prompt。
  • toTeacherHomeworkAnalysisPrompt(teacherHomework): 接收教师作业数据，将 teacherHomeworkPrePrompt（教师作业分析模板）与数据拼接，生成教师作业分析的 prompt。

• homeworkCorrection.js

  • toStudentHomeworkCorrectionPrompt(studentHomework): 接收学生作业数据，将 prePrompt（作业批改模板）与数据拼接，生成作业批改的 prompt。

• studyPathPrompt.js

  • toStudyPathPrompt(prompt): 接收用户输入的内容，将 prePrompt（学习路径生成模板）、用户输入和 afterPrompt（返回格式示例）拼接，生成学习路径生成的 prompt。

src/utils/

src/utils/ 目录下包含多个工具函数文件，用于处理请求和响应。具体如下：

• requestTemplateUtils.js

  • handlePostRequest(ctx, service, successMessage): 处理 POST 请求，调用传入的 service 函数处理请求体，并封装标准响应格式（包含 code、message、data）。如果处理过程中出现错误，则返回错误信息。
  • handleGetRequest(ctx, service, successMessage): 处理 GET 请求，调用传入的 service 函数处理查询参数，并封装标准响应格式（包含 code、message、data）。如果处理过程中出现错误，则返回错误信息。

• responseUtils.js

  • modifyAiResponse(response): 调整 AI 的返回结果，去掉其中的 <think> 标签及其内容，以及首部的换行符，最终返回格式化后的结果。

src/aiApi/aiApi.js

src/aiApi/aiApi.js 是 AI 接口调用的封装文件，负责与大模型（如 OpenAI）进行交互。具体功能如下：

• 依赖引入：引入 OpenAI 模块，并从 config.js 中获取 API 密钥、API 基础 URL 和模型名称。
• OpenAI 客户端初始化：通过 new OpenAI({ apiKey, baseURL }) 初始化 OpenAI 客户端。
• invokeAI 函数：封装了大模型调用的核心逻辑：
  • 接收 prompt 参数（可以是字符串或对话历史数组）。
  • 将 prompt 转换为大模型所需的消息格式。
  • 调用 openai.chat.completions.create 方法，传入模型名称和消息，获取大模型的回复。
  • 返回大模型回复的内容。

src/constants/

src/constants/ 目录下包含常量定义文件，用于统一管理返回码等常量。具体如下：

• resultConstants.js
  • 定义了三个常量：
    • SUCCESS: 表示请求成功，值为 0。
    • ERROR: 表示请求失败，值为 1。
    • WARNING: 表示请求警告，值为 2。
  • 这些常量用于在响应中统一标识请求状态。

src/config/

src/config/ 目录下包含配置文件，用于管理服务器和 AI 服务的配置参数。具体如下：

• config.js
  • 使用 dotenv 加载环境变量配置文件（env.env）。
  • 定义了以下配置参数：
    • PORT: 服务器端口，值为 “9999”。
    • HOST: 服务器主机，值为 “0.0.0.0”。
    • API_KEY: 从环境变量中获取 API 密钥。
    • AI_API_BASE_URL: 从环境变量中获取 AI API 的基础 URL。
    • AI_MODEL: 从环境变量中获取 AI 模型名称。
  • 这些配置参数用于初始化服务器和 AI 服务。