XMZZUZHI/FC/math-expert

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

math-expert/README.md

祁筱欣

chore: 更新依赖和文档并修改脚本权限

0ea69836

PreviewCode viewBlame

Raw

函数求值专家 - 使用文档

1. 概述

函数求值专家是基于 LangChain 框架开发的智能数学助手模板，专门用于解决函数求值和数值计算问题。该模板集成了代码解释器能力，可以处理复杂的数学表达式、方程求解、数值分析等任务。

1.1 适用场景

数学函数计算与求值
方程求解与验证
数值分析与统计计算
数据处理与公式推导

1.2 核心功能

自动理解数学问题并生成求解代码
实时执行计算并返回准确结果
支持复杂函数和多步骤计算
流式响应，实时展示计算过程
数学公式 LaTeX 渲染
代码执行结果可视化

1.3 技术特点

基于 LangChain 框架
集成代码解释器沙箱
支持 Python 数值计算（NumPy、Pandas）
前后端分离架构
部署于阿里云函数计算 FC3

2. 快速开始

2.1 前置要求

阿里云账号
AgentRun 平台访问权限
基本的 Python 知识

2.2 快速部署

克隆项目


git clone https://cnb.cool/XMZZUZHI/AgentRun/math-expert.git
cd math-expert

配置环境变量

在 AgentRun 控制台配置以下参数：
- MODEL_SERVICE: 模型服务地址
- MODEL_NAME: 模型名称（推荐 qwen3-max）
- CODE_INTERPRETER_TEMPLATE: 代码解释器沙箱模板名称
部署应用

使用阿里云 Serverless Devs 工具部署：
```
cd src
s deploy
```
访问应用

部署完成后，访问提供的 URL 即可使用函数求值助手。

2.3 快速测试

在界面中输入以下测试问题：

帮我计算一下 y=sin(x)+2x 和 y=x² 的交点

系统将自动分析问题、生成计算代码、执行计算并返回结果。

3. 项目结构


workspace/
├── README.md                          # 项目文档
├── LICENSE                            # AGPL-3.0 开源协议
├── agentrun-app.yaml                  # 应用元数据配置
├── publish.yaml                       # 发布配置
├── .cnb.yml                           # CNB 构建配置
├── install_agents.sh                  # 安装 iFlow 智能体脚本
├── install_gpg_keys.sh                # 安装 GPG 密钥脚本
├── src/
│   ├── build.yaml                     # 构建配置
│   ├── s.yaml                         # Serverless 应用配置
│   └── code/
│       ├── agentrun-backend/          # 后端代码
│       │   ├── main.py               # Agent 主程序
│       │   └── requirements.txt      # Python 依赖
│       └── agentrun-frontend/         # 前端代码
│           ├── server.py             # HTTP 服务器
│           ├── index.html            # 主界面
│           ├── math-render-test.html # 数学渲染测试
│           ├── math-test.html        # 数学公式测试
│           ├── test-math-api.html    # API 测试
│           ├── placeholder-test.html # 占位符测试
│           ├── render-test.html      # 渲染测试
│           └── start.sh              # 启动脚本

3.1 目录说明

目录/文件	说明
`src/code/agentrun-backend/`	后端服务代码，包含 Agent 实现
`src/code/agentrun-frontend/`	前端服务代码，包含 Web 界面
`src/s.yaml`	Serverless 应用配置文件
`src/build.yaml`	构建配置文件
`agentrun-app.yaml`	应用元数据和模板参数
`publish.yaml`	发布配置和版本信息

4. 技术架构

4.1 架构概述

使用框架： LangChain
Agent 架构： 单 Agent 架构，专注于数学计算任务
技术特点： 集成代码解释器，支持 Python 代码执行和数值计算

该模板采用单一专业 Agent 设计，通过大语言模型的推理能力结合代码执行工具，实现高精度的数学计算。用户可在控制台选择适合的大语言模型（如 GPT-4、Claude 等）来驱动 Agent。

4.2 系统架构图

4.3 前后端分离架构图

4.4 架构说明

前端层 (Frontend Layer)

职责： 提供用户界面，处理用户交互，渲染响应内容

主要组件：

HTTP 服务器 (server.py)：提供静态文件服务和 API 代理
用户界面 (HTML/CSS)：响应式设计，支持移动端和桌面端
JavaScript 逻辑：处理用户输入、API 请求、流式响应渲染
前端依赖库：
- Marked.js：Markdown 文本渲染
- KaTeX：LaTeX 数学公式渲染
- Highlight.js：代码语法高亮

技术特点：

纯静态文件部署，无需服务器端渲染
支持 CORS 跨域请求
流式响应实时渲染
工具输出 JSON 提取和分离展示

后端层 (Backend Layer)

职责： 处理业务逻辑，调用 AI 模型，执行代码计算

主要组件：

AgentRun Server：提供 OpenAI 兼容的 API 接口
LangChain Agent：智能体核心，负责任务规划和工具调用
系统提示词：定义 Agent 的角色和行为规范
工具集：代码解释器等工具
大语言模型：提供自然语言理解和代码生成能力
代码解释器沙箱：安全隔离的 Python 代码执行环境

技术特点：

基于 LangChain 框架
支持流式和非流式响应
代码执行沙箱隔离
会话管理和状态保持

数据流向

请求阶段：
- 用户在浏览器输入问题
- 前端通过 API 代理发送 POST 请求到后端
- 后端接收请求并传递给 Agent
处理阶段：
- Agent 分析问题，生成计算策略
- 调用大语言模型生成 Python 代码
- 调用代码解释器执行代码
- 代码解释器在沙箱中运行，使用 NumPy/Pandas 进行计算
响应阶段：
- Agent 获取计算结果
- 生成 Markdown 格式的计算报告
- 通过流式响应返回前端
- 前端实时渲染 Markdown 和数学公式
- 提取并展示代码执行结果

优势

前后端分离：前端和后端独立开发和部署
可扩展性：可以独立扩展前端或后端
安全性：代码执行在沙箱中隔离，确保安全
实时性：流式响应提供更好的用户体验
灵活性：前端可以轻松适配不同的 UI 框架

4.5 数据流

数据流详细说明

数据流阶段分解：

阶段 1: 用户输入

数据格式：纯文本
数据来源：用户在浏览器输入框输入
示例："帮我计算一下y=sin(x)+2x和y=x^2的交点"
数据量：通常 10-500 字符
编码：UTF-8

阶段 2: 前端请求

数据格式：JSON 对象

数据结构：


{
  "messages": [
    {
      "role": "user",
      "content": "帮我计算一下y=sin(x)+2x和y=x^2的交点"
    }
  ],
  "stream": true
}

数据量：约 100-1000 字节
传输方式：HTTP POST 请求
请求头：Content-Type: application/json, x-agentrun-session-id: agentrun-math-demo

阶段 3: Agent 处理

数据格式：Python Dict

数据结构：


{
  "messages": [
    {"role": "user", "content": "..."}
  ],
  "tools": [...],  # 代码解释器工具
  "system_prompt": "..."  # 系统提示词
}

数据量：约 1-5 KB（包含系统提示词）
处理逻辑：Agent 分析问题，生成计算策略

阶段 4: LLM 调用

数据格式：JSON 流（流式）或 JSON 对象（非流式）

数据结构：OpenAI 兼容格式


{
  "model": "qwen3-max",
  "messages": [...],
  "stream": true
}

响应格式：
- 流式：data: {"choices": [{"delta": {"content": "..."}}]}
- 非流式：{"choices": [{"message": {"content": "..."}}]}
数据量：响应通常 1-50 KB
超时设置：180 秒

阶段 5: 工具调用

数据格式：JSON 对象

数据结构：


{
  "tool_calls": [
    {
      "name": "code_interpreter",
      "arguments": {
        "code": "import numpy as np\n..."
      }
    }
  ]
}

数据量：代码通常 100-2000 字符
调用方式：通过 AgentRun SDK 调用沙箱工具

阶段 6: 沙箱执行

数据格式：JSON 对象

输入结构：


{
  "code": "import numpy as np\n...",
  "timeout": 300
}

输出结构：


{
  "output": "计算结果...",
  "error": null,
  "execution_time": 1.5
}

数据量：结果通常 100-5000 字符
超时设置：300 秒（沙箱空闲超时）
可用库：NumPy、Pandas（仅限这两个库）

阶段 7: 响应生成

数据格式：Markdown 字符串
数据结构：包含 LaTeX 公式、代码块、计算结果

示例：


通过数值计算，我们找到了函数 $ y = \\sin x + x $ 和 $ y = x^2 $ 的交点。

这些交点对应于方程：
$$\\sin x + x = x^2$$

经过计算，得到两个交点的横坐标近似为：
1. $ x_1 \\approx 0 $
2. $ x_2 \\approx 1.6175 $

数据量：通常 500-10000 字符
生成方式：Agent 综合处理 LLM 响应和工具执行结果

阶段 8: 流式输出

数据格式：SSE (Server-Sent Events)

数据结构：


data: {"content": "通过数值计算，"}

data: {"content": "我们找到了函数"}

data: {"content": " $ y = \\sin x + x $ ..."}

数据量：分块传输，每块 100-1000 字节
传输方式：HTTP 响应流
响应头：Content-Type: text/event-stream, Cache-Control: no-cache

阶段 9: 前端渲染

数据格式：HTML + CSS
数据结构：渲染后的 DOM 结构
渲染组件：
- Marked.js：Markdown 文本渲染
- KaTeX：LaTeX 数学公式渲染
- Highlight.js：代码语法高亮
数据量：通常 1-50 KB
展示方式：实时渲染，逐步显示

数据流特点

流式处理：

LLM 响应采用流式输出，减少用户等待时间
前端实时渲染，提供更好的用户体验
SSE 协议保证数据传输的可靠性

数据转换：

纯文本 → JSON（前端请求）
JSON → Python Dict（后端处理）
Python Dict → JSON 流（LLM 调用）
JSON 流 → JSON 对象（工具调用）
JSON 对象 → Markdown（响应生成）
Markdown → HTML（前端渲染）

数据隔离：

代码执行在沙箱中隔离，确保安全
每个会话独立，数据不共享
支持多用户并发访问

性能优化：

流式响应减少首字节时间（TTFB）
分块传输降低内存占用
沙箱复用提高执行效率

4.6 Agent 架构设计

4.6.1 Agent 内部架构

Agent 内部架构说明

LangChain Agent 采用分层架构设计，包含输入层、推理层、执行层和输出层：

输入层组件：

用户输入：接收用户的数学问题或计算请求
系统提示词：定义 Agent 的角色、行为规范和输出格式要求
工具配置：注入可用的工具集（代码解释器）

推理层组件：

规划引擎：基于 ReAct (Reasoning + Acting) 模式进行任务规划
大语言模型：提供自然语言理解和代码生成能力
决策模块：判断是否需要调用工具或直接回答

执行层组件：

工具集：管理和调用代码解释器工具
代码解释器沙箱：安全隔离的 Python 代码执行环境
Python 运行时：提供 NumPy 和 Pandas 等数值计算库

输出层组件：

流式生成器：实时生成和流式输出响应内容
响应内容：格式化为 Markdown 的计算报告

数据流向：

用户输入和系统提示词注入 Agent 核心
规划引擎分析任务并生成执行计划
大语言模型根据计划生成 Python 代码或直接回答
如需计算，通过工具集调用代码解释器执行代码
计算结果返回 Agent 进行综合处理
流式生成器实时输出 Markdown 格式的响应

4.6.2 Agent 交互流程

Agent 交互流程说明

Agent 交互流程分为两个主要模式：流式响应模式和非流式响应模式。

流式响应模式流程：

请求阶段
- 用户在前端输入数学问题
- 前端构建 API 请求发送到后端
- 后端创建 AgentRequest 并调用 invoke_agent()
流式生成阶段
- Agent 检测到 stream=true，创建 stream_generator()
- Agent 将消息上下文发送给大语言模型
- 大语言模型返回生成的内容片段
工具调用阶段（如需要）
- Agent 判断需要调用代码解释器工具
- 代码解释器沙箱创建 Python 执行环境
- 导入 NumPy/Pandas 数学库
- 执行大语言模型生成的 Python 代码
- 数学库返回计算结果
- 沙箱将结果返回给 Agent
- Agent 将工具结果发送给大语言模型继续生成
响应阶段
- Agent 逐段 yield 内容
- 后端通过 SSE (Server-Sent Events) 流式推送到前端
- 前端实时渲染 Markdown 和数学公式
- 用户看到逐步生成的计算报告

非流式响应模式流程：

与流式模式类似，但所有内容在服务端完整生成后一次性返回，适合短时间可完成的简单计算任务。

关键特性：

流式响应提供更好的用户体验，实时展示计算过程
工具调用自动判断，无需用户干预
代码执行在隔离沙箱中，确保安全
支持 Markdown 格式和 LaTeX 数学公式渲染

4.6.3 Agent 生态系统

Agent 生态系统说明

函数求值专家 Agent 依赖于完整的生态系统，从用户界面到基础设施各层协同工作。

用户层：

用户通过浏览器或客户端访问应用
提交数学计算请求，查看计算结果

应用层：

前端服务：提供 Web 界面，处理用户交互
后端服务：处理业务逻辑，调用 Agent
函数求值专家应用：整体应用，部署于阿里云函数计算 FC3

Agent 核心：

LangChain Agent：智能体核心，负责任务规划和工具调用
系统提示词：定义 Agent 的角色和行为规范
工具集：管理代码解释器等工具

AgentRun 平台：

AgentRun SDK：提供 LangChain 集成和 Server 能力（v0.0.7）
AgentRun Server：提供 OpenAI 兼容的 API 接口
AgentRun 平台：Agent 托管和管理平台

AI 服务层：

模型服务：提供大语言模型访问接口（MODEL_SERVICE）
大语言模型：提供 AI 推理能力（qwen3-max）
沙箱模板：定义代码执行环境（CODE_INTERPRETER_TEMPLATE）
代码解释器沙箱：提供安全的 Python 代码执行环境（qwen3-coder-plus）

计算库层：

Python 运行时：Python 3.12 解释器
NumPy：提供高性能数值计算能力
Pandas：提供数据处理和分析能力

基础设施层：

阿里云函数计算 FC3：提供无服务器计算能力
网络服务：提供网络连接和负载均衡
存储服务：提供日志和临时数据存储

生态依赖关系：

Agent 通过 AgentRun SDK 接入 AgentRun 平台
AgentRun Server 路由请求到模型服务和沙箱服务
SDK 依赖 LangChain 框架实现 Agent 能力
应用部署于 FC3，利用其无服务器特性
用户通过浏览器访问前端服务，前端通过代理调用后端

优势：

托管式服务：Agent 和 AI 能力由平台托管，降低运维复杂度
弹性伸缩：基于 FC3，按需扩展，成本优化
安全隔离：代码执行在沙箱中，确保系统安全
易于集成：通过 SDK 和标准接口轻松集成

4.6.4 Agent 状态转换图

Agent 状态转换说明

Agent 在执行数学计算任务时，会经历多个状态转换，每个状态都有明确的职责和转换条件。

状态说明：

初始化状态

触发条件：应用启动时，通过 create_agent() 创建 Agent 实例
持续时间：一次性初始化，约 1-2 秒
主要操作：加载模型配置、初始化工具集、设置系统提示词
转换条件：初始化完成后自动进入等待请求状态

等待请求状态

触发条件：Agent 创建完成或上一轮对话结束
持续时间：持续等待，直到收到请求
主要操作：监听 9000 端口，等待 API 请求
转换条件：收到用户请求进入推理中状态，或请求格式错误进入错误状态

推理中状态

触发条件：接收到有效的用户消息
持续时间：取决于问题复杂度，通常 1-30 秒
主要操作：LLM 分析问题，生成计算策略
转换条件：需要代码执行进入工具调用状态，或直接回答进入流式输出状态

工具调用状态

触发条件：LLM 判断需要执行代码计算
持续时间：约 0.5-2 秒
主要操作：准备工具调用参数，发送到代码解释器
转换条件：调用成功进入沙箱执行状态

沙箱执行状态

触发条件：工具调用准备完成
持续时间：取决于代码复杂度，通常 1-10 秒
主要操作：在沙箱中执行 Python 代码，使用 NumPy/Pandas 计算
转换条件：执行成功返回结果进入推理中状态，或执行失败进入错误状态

流式输出状态

触发条件：LLM 开始生成响应内容
持续时间：取决于响应长度，通常 2-20 秒
主要操作：通过 stream_generator() 逐步生成内容并返回
转换条件：流式结束进入完成状态，或中断进入错误状态

完成状态

触发条件：流式输出结束或错误处理完成
持续时间：约 0.1-0.5 秒
主要操作：整理最终结果，返回给前端
转换条件：进入等待请求状态准备下一轮对话，或会话结束

错误状态

触发条件：任何步骤发生异常
持续时间：约 0.5-2 秒
主要操作：捕获异常，记录日志，返回错误信息
转换条件：错误处理完成进入完成状态

状态转换规则：

正常流程：初始化 → 等待请求 → 推理中 → 工具调用 → 沙箱执行 → 推理中 → 流式输出 → 完成 → 等待请求
直接回答流程：初始化 → 等待请求 → 推理中 → 流式输出 → 完成 → 等待请求
错误处理流程：任意状态 → 错误状态 → 完成 → 等待请求

超时处理机制：

模型调用超时：通过 Config(timeout=180) 设置，默认 180 秒
沙箱执行超时：通过 sandbox_idle_timeout_seconds=300 设置，默认 300 秒
流式输出超时：前端代理设置 timeout=300，默认 300 秒

流式与非流式模式差异：

特性	流式模式	非流式模式
响应方式	逐步返回	一次性返回
用户体验	实时展示计算过程	等待完整结果
适用场景	复杂计算、长时间任务	简单计算、快速响应
状态流转	经过流式输出状态	直接完成

关键代码位置：

状态初始化：main.py:9000 - create_agent()
状态转换：main.py:9000 - invoke_agent()
流式生成：main.py:9000 - stream_generator()
错误处理：main.py:9000 - try-except 块

性能优化建议：

减少状态转换次数：对于简单问题，优先使用直接回答流程
优化工具调用：合并多次工具调用为单次批量调用
缓存常用计算：对于重复计算，可考虑结果缓存
监控状态持续时间：设置告警阈值，及时发现性能问题

4.7 核心组件关系

核心组件关系说明

本节详细展示函数求值专家应用中各核心组件之间的关系、接口和通信方式，帮助开发者理解系统的组件结构和职责划分。

用户交互层

职责： 提供用户访问入口，接收用户输入和展示计算结果

核心组件：

浏览器：Chrome、Firefox、Safari 等主流浏览器
客户端：移动端和桌面端客户端

通信方式：

通过 HTTP 协议与前端服务层通信
支持 GET、POST、PUT、DELETE 等 HTTP 方法

前端服务层

职责： 提供 Web 界面，处理用户交互，渲染响应内容

核心组件：

HTTP 服务器：基于 Python 的 HTTP 服务器（server.py），监听 8000 端口
静态文件服务：提供 index.html 等静态文件服务
UI 组件：HTML/CSS 构建的用户界面
JavaScript 逻辑：处理用户输入、API 请求、流式响应渲染
前端依赖库：Marked.js（Markdown 渲染）、KaTeX（数学公式渲染）、Highlight.js（代码高亮）

通信方式：

接收来自用户交互层的 HTTP 请求
通过 API 代理与后端服务层通信
使用 SSE（Server-Sent Events）接收流式响应

关键接口：

GET /：返回主页面
POST /api/*：API 代理接口，转发请求到后端

后端服务层

职责： 处理业务逻辑，调用 AI 模型，执行代码计算

核心组件：

AgentRun Server：提供 OpenAI 兼容的 API 接口（main.py），监听 9000 端口
LangChain Agent：智能体核心，负责任务规划和工具调用
规划引擎：基于 ReAct (Reasoning + Acting) 模式进行任务规划
LLM 接口：与大语言模型的调用接口
工具接口：与代码解释器等工具的调用接口
系统提示词：定义 Agent 的角色和行为规范
工具集：管理代码解释器等工具

通信方式：

接收来自前端服务层的 API 请求
通过 LLM 接口调用大语言模型服务
通过工具接口调用代码解释器服务

关键接口：

POST /openai/v1/chat/completions：聊天完成接口
支持流式和非流式响应

AI 服务层

职责： 提供 AI 推理能力和代码执行能力

核心组件：

LLM 服务：大语言模型服务（qwen3-max），提供 AI 推理能力
代码解释器沙箱：安全的 Python 代码执行环境（qwen3-coder-plus）
NumPy：高性能数值计算库
Pandas：数据处理和分析库

通信方式：

接收来自后端服务层的模型调用请求
接收来自后端服务层的工具调用请求
使用 Python 运行时执行代码

关键接口：

LLM 模型调用接口：接收提示词，返回生成内容
代码执行接口：接收 Python 代码，返回执行结果

基础设施层

职责： 提供计算、网络、存储等基础服务

核心组件：

阿里云 FC3：无服务器函数计算平台，提供弹性伸缩能力
AgentRun 平台：Agent 托管和管理平台
网络服务：API 网关，提供负载均衡和路由
存储服务：日志存储和临时数据存储

部署关系：

前端服务层部署于阿里云 FC3
后端服务层部署于阿里云 FC3
AI 服务层托管于 AgentRun 平台

组件职责划分

组件层	核心职责	关键组件
用户交互层	用户访问	浏览器、客户端
前端服务层	用户界面	HTTP 服务器、UI、JS
后端服务层	业务逻辑	Server、Agent、规划引擎
AI 服务层	AI 能力	LLM 服务、代码解释器
基础设施层	基础服务	FC3、AgentRun、网络、存储

通信协议

通信路径	协议	说明
用户交互层 → 前端服务层	HTTP	标准 HTTP 请求
前端服务层 → 后端服务层	HTTP	API 代理
后端服务层 → AI 服务层	自定义协议	模型调用、工具调用
前端服务层 → 基础设施层	部署协议	函数计算部署
后端服务层 → 基础设施层	托管协议	Agent 托管

优势

清晰的职责划分：每个组件层有明确的职责和边界
松耦合设计：组件之间通过接口通信，降低耦合度
易于扩展：可以独立扩展各个组件层
便于维护：组件职责清晰，便于维护和升级
高可用性：各组件层可以独立部署和扩展

5. 依赖关系

5.1 依赖关系图

5.2 依赖说明

后端依赖

依赖名称	版本	用途
Python	3.12	运行时环境
agentrun-sdk	0.0.7	AgentRun SDK，包含 LangChain 和 Server 集成
LangChain	-	Agent 框架
NumPy	-	数值计算库（代码解释器中）
Pandas	-	数据处理库（代码解释器中）

前端依赖

依赖名称	版本	用途
Marked.js	11.0.0	Markdown 渲染
KaTeX	0.16.9	数学公式渲染
Highlight.js	11.9.0	代码语法高亮

运行时依赖

依赖名称	说明
阿里云函数计算 FC3	云函数计算平台
AgentRun 平台	Agent 托管和管理平台
大语言模型 (qwen3-max)	AI 推理引擎
代码解释器沙箱 (qwen3-coder-plus)	Python 代码执行环境

6. 功能说明

6.1 主要功能模块

函数求值： 计算各类数学函数在指定点的值
方程求解： 求解代数方程、微分方程等
数值分析： 执行积分、微分、极限等数值计算
代码生成： 自动生成 Python 计算代码并执行
流式响应： 实时展示计算过程和结果
公式渲染： 支持 LaTeX 数学公式渲染
代码高亮： 支持代码语法高亮显示

6.2 Agent 能力

理解自然语言描述的数学问题
调用代码解释器执行计算
验证结果并提供详细解释
处理计算错误并自动修正
生成 Markdown 格式的计算报告

6.3 工作流程

工作流程说明

步骤详解：

用户输入数学问题
- 用户通过浏览器输入数学问题（自然语言或数学表达式）
- 支持函数求值、方程求解、数值分析等多种数学任务
Agent 分析问题
- LangChain Agent 分析问题的类型和复杂度
- 提取关键信息（函数、参数、约束条件等）
生成计算策略
- Agent 基于问题分析结果生成计算策略
- 确定是否需要调用代码解释器工具
判断是否需要代码执行
- 需要代码执行：对于复杂的计算任务（如数值积分、方程求解等）
  - 生成 Python 代码
  - 调用代码解释器执行
  - 使用 NumPy/Pandas 进行计算
- 直接生成答案：对于简单的计算任务（如基本运算、函数求值等）
  - 直接生成答案
Agent 处理结果
- 整合计算结果和工具输出
- 验证结果的正确性
- 生成详细的解释说明
格式化为 Markdown
- 将结果格式化为 Markdown 格式
- 包含数学公式（LaTeX）、代码块、计算结果等
流式返回前端
- 通过流式响应将内容逐步返回前端
- 提供更好的用户体验
前端渲染
- 前端使用 Marked.js 渲染 Markdown
- 使用 KaTeX 渲染数学公式
- 使用 Highlight.js 高亮代码
展示给用户
- 用户看到完整的计算报告
- 包含计算过程、结果和解释

关键特性：

自动判断是否需要代码执行
支持流式响应，实时展示计算过程
代码执行在安全沙箱中进行
支持 Markdown 格式和 LaTeX 数学公式
自动处理计算错误并修正

7. 配置指南

7.1 控制台配置

在 AgentRun 控制台中进行可视化配置：

模型选择： 选择适合的大语言模型（推荐 qwen3-max）
温度参数： 建议设置为 0-0.3，确保计算准确性
工具配置： 确保代码解释器工具已启用
超时设置： 根据计算复杂度设置合理的执行超时时间（默认 180 秒）

7.2 环境变量

环境变量	说明	默认值
`MODEL_SERVICE`	模型服务地址	-
`MODEL_NAME`	模型名称	qwen3-max
`CODE_INTERPRETER_TEMPLATE`	代码解释器沙箱模板名称	-
`BACKEND_URL`	后端服务 URL（前端使用）	-

7.3 资源配置

资源项	前端	后端
内存	1024MB	2048MB
CPU	1核	1.0核
超时	600秒	180秒
并发	100	10

8. 部署指南

8.0 部署架构

本节展示函数求值专家应用部署到阿里云函数计算 FC3 后的完整架构，包括各个组件之间的关系和资源配置。

部署架构说明

前端服务 (agentrun_frontend)

组件类型：阿里云函数计算 FC3
运行时：custom.debian10
端口：8000
资源配置：
- 内存：1024MB
- CPU：1核
- 并发：100
- 超时：600秒
触发器：HTTP 触发器（支持 GET/POST/PUT/DELETE）
自定义域名：自动分配
主要功能：提供 Web 界面，处理用户交互，渲染响应内容

后端服务 (agentrun_backend)

组件类型：AgentRun 平台
运行时：Python 3.12
端口：9000
资源配置：
- 内存：2048MB
- CPU：1.0核
- 并发：10
端点：prod（版本 LATEST）
环境变量：
- MODEL_SERVICE：模型服务地址
- MODEL_NAME：模型名称（qwen3-max）
- CODE_INTERPRETER_TEMPLATE：代码解释器沙箱模板名称
- BACKEND_URL：后端服务 URL
主要功能：处理业务逻辑，调用 AI 模型，执行代码计算

AI 服务层

大语言模型：qwen3-max，提供 AI 推理能力
代码解释器沙箱：qwen3-coder-plus，提供安全的 Python 代码执行环境
计算库：NumPy（数值计算）、Pandas（数据处理）

基础设施层

阿里云函数计算 FC3：无服务器计算平台，提供弹性伸缩能力
API 网关：API 请求路由和管理
RAM 权限管理：权限控制（AliyunAgentRunFullAccess）
VPC 网络：网络隔离和安全

8.1 部署流程

本节展示从零开始部署函数求值专家应用到阿里云 FC3 的完整流程，包括前置准备、构建、部署、配置和验证五个阶段。

部署流程详解

阶段 1: 前置准备

安装 Serverless Devs 工具
```
npm install -g @serverless-devs/s
```
- 确保已安装 Node.js 和 npm
- 使用 -g 参数全局安装
配置阿里云凭证
```
s config add
```
- 输入 AccessKey ID
- 输入 AccessKey Secret
- 输入 Account ID
- 验证凭证是否有效
准备模型和沙箱
- 在 AgentRun 平台创建大语言模型（qwen3-max）
- 在 AgentRun 平台创建代码解释器沙箱（qwen3-coder-plus）
- 创建 RAM 角色并授权（AliyunAgentRunFullAccess）

阶段 2: 构建后端依赖

进入项目目录
```
cd src
```
构建后端服务
```
s build agentrun_backend
```
- 读取 build.yaml 配置
- 创建 python 目录
- 安装 Python 依赖到 ./python 目录
- 打包依赖用于部署

阶段 3: 部署应用

部署所有服务
```
s deploy
```
- 读取 s.yaml 配置
- 解析模板参数（vars）
- 部署前端服务（agentrun_frontend）
- 部署后端服务（agentrun_backend）
- 获取部署信息（URL、端点）

阶段 4: 配置环境变量

配置后端环境变量：
- MODEL_SERVICE：模型服务地址
- MODEL_NAME：模型名称（qwen3-max）
- CODE_INTERPRETER_TEMPLATE：代码解释器沙箱模板名称
- BACKEND_URL：后端服务 URL

阶段 5: 验证部署

获取部署信息
```
s info
```
- 获取前端 URL
- 获取后端 URL
- 获取端点信息
测试前端访问
```
curl http://<frontend-url>
```
- 检查前端是否可访问
- 验证页面加载正常

测试 API 调用


curl http://<backend-url>/openai/v1/chat/completions \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "帮我计算一下y=sin(x)+2x和y=x^2的交点"
      }
    ],
    "stream": true
  }'

发送测试请求
验证 API 是否正常工作
检查流式响应

8.2 部署到阿里云 FC3

前置条件

安装 Serverless Devs 工具
```
npm install -g @serverless-devs/s
```
配置阿里云凭证
```
s config add
```

部署步骤

进入项目目录
```
cd src
```
构建后端依赖
```
s build agentrun_backend
```
部署应用
```
s deploy
```
记录部署完成后提供的 URL

8.3 本地开发

后端开发

安装依赖


cd src/code/agentrun-backend
pip install -r requirements.txt

设置环境变量


export MODEL_SERVICE="your-model-service"
export MODEL_NAME="your-model-name"
export CODE_INTERPRETER_TEMPLATE="your-sandbox-template"

启动后端服务
```
python main.py
```

前端开发

启动前端服务


cd src/code/agentrun-frontend
python server.py

访问 http://localhost:8000

9. 开发指南

9.1 代码规范

Python 代码遵循 PEP 8 规范
JavaScript 代码使用 ES6+ 语法
注释清晰，函数命名语义化

9.2 添加新功能

后端添加新工具

在 main.py 中导入新的工具
将工具添加到 create_agent() 的 tools 参数中
更新系统提示词（如需要）

前端添加新功能

在 index.html 中添加 UI 元素
在 JavaScript 中添加事件处理
更新样式（如需要）

9.3 调试技巧

使用 logger.info() 输出调试信息
检查浏览器控制台的错误信息
查看函数计算日志

9.4 开发工作流程

开发工作流程说明

阶段详解：

需求阶段

需求分析
- 明确功能需求和用户场景
- 分析技术可行性和实现方案
- 评估工作量和时间成本
制定开发计划
- 设计技术方案和架构
- 制定详细的时间表
- 确定里程碑和交付物

开发阶段

后端开发
- 在 main.py 中实现后端逻辑
- 添加新的工具或功能
- 更新系统提示词（如需要）
- 编写单元测试
前端开发
- 在 index.html 中添加 UI 元素
- 在 JavaScript 中添加事件处理
- 更新样式和布局
- 进行功能测试和兼容性测试
测试
- 后端测试：单元测试、集成测试
- 前端测试：功能测试、兼容性测试
- 确保所有测试通过

提交阶段

提交代码
- 使用 git commit 提交代码
- 编写清晰的提交信息
- 遵循提交信息规范
推送到远程
- 使用 git push 推送到远程仓库
- 确保推送成功

审查阶段

创建 Pull Request
- 在 GitHub 上创建 Pull Request
- 详细描述修改内容和测试结果
代码审查
- 其他开发者进行代码审查
- 提出修改建议或问题
- 讨论技术方案
修改和合并
- 根据审查意见进行修改
- 重新提交和推送
- 审查通过后合并到主分支

部署阶段

部署到生产环境
- 使用 s deploy 部署应用
- 等待部署完成
- 记录部署信息
验证部署
- 进行功能测试
- 检查日志和监控
- 确保应用正常运行

最佳实践：

遵循代码规范（PEP 8、ES6+）
编写清晰的注释和文档
编写单元测试和集成测试
使用 Git 分支管理（feature、develop、master）
进行代码审查（Code Review）
使用持续集成/持续部署（CI/CD）
定期备份数据和配置

10. API 文档

10.1 接口列表

接口	方法	说明
`/openai/v1/chat/completions`	POST	聊天完成接口

10.2 聊天完成接口

请求 URL： POST /openai/v1/chat/completions

请求头：


Content-Type: application/json
x-agentrun-session-id: agentrun-math-demo

请求体：


{
  "messages": [
    {
      "role": "user",
      "content": "帮我计算一下y=sin(x)+2x和y=x^2的交点"
    }
  ],
  "stream": true
}

请求参数：

参数	类型	必填	说明
messages	array	是	消息列表
stream	boolean	否	是否流式响应（默认 true）

响应（流式）：


data: {"content": "通过数值计算，我们找到了函数..."}
data: {"content": "这些交点对应于方程..."}
data: [DONE]

响应（非流式）：


{
  "messages": [
    {
      "role": "assistant",
      "content": "计算结果..."
    }
  ]
}

10.3 错误码

错误码	说明
400	请求参数错误
500	服务器内部错误
504	请求超时

10.4 SSE 通信流程

SSE 通信流程说明

本节详细展示函数求值专家应用中 SSE（Server-Sent Events）流式通信的完整流程，包括连接建立、数据传输、错误处理和性能优化等技术细节。

阶段 1：请求建立

用户输入
- 用户在浏览器中输入数学问题
- 点击发送按钮触发请求

构建请求

JavaScript 构建请求体


const requestBody = {
    messages: [{ role: 'user', content: message }],
    stream: true
};

设置 stream: true 启用流式模式

发送请求

使用 Fetch API 发送 POST 请求


const response = await fetch('/api/openai/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(requestBody)
});

转发请求
- 前端服务代理转发到后端服务
- 保持请求头和请求体

阶段 2：连接建立

接收请求
- 后端服务接收 AgentRequest
- 提取请求参数
检查流式
- 检查 request.stream 是否为 true
- 启用流式响应模式
调用 Agent
- 调用 invoke_agent(request) 函数
- 传递请求参数

创建生成器

Agent 创建 stream_generator() 生成器函数


def stream_generator():
    result = agent.stream(input, stream_mode="messages")
    for chunk in result:
        yield pydash.get(chunk, "[0].content")
return stream_generator()

设置响应头

AgentRun Server 自动设置响应头


Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

阶段 3：流式数据传输循环

流式生成
- Agent 调用 agent.stream(input, stream_mode="messages")
- 开始流式生成内容
返回片段
- LLM 返回内容片段
- 每次返回一小段文本
Yield 数据
- Agent 通过 yield 返回内容片段
- 保持连接打开
SSE 封装
- 后端封装为 SSE 格式
```
data: {"content": "内容片段"}
```
SSE 推送
- 通过 SSE 流式推送到前端
- 保持长连接

读取数据

JavaScript 使用 reader.read() 读取数据


const reader = response.body.getReader();
while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // 处理数据
}

解码数据

使用 TextDecoder 解码数据


const decoder = new TextDecoder();
const chunk = decoder.decode(value, { stream: true });

解析格式

解析 SSE 格式，提取 data: {...}
使用缓冲区处理不完整的行


const lines = buffer.split('\n');
buffer = lines.pop() || '';
for (const line of lines) {
    if (line.startsWith('data: ')) {
        const data = line.slice(6).trim();
        // 处理数据
    }
}

JSON 解析

JSON.parse(data) 解析 JSON


const json = JSON.parse(data);
const delta = json.choices?.[0]?.delta;
if (delta?.content) {
    accumulatedText += delta.content;
}

累积内容
- 累积内容到 accumulatedText
- 保存完整的响应内容

实时渲染

实时渲染预览（每 200ms 更新一次）


const UPDATE_INTERVAL = 200;
if (now - lastUpdateTime > UPDATE_INTERVAL) {
    showStreamingStatus(currentMessageElement, accumulatedText);
    lastUpdateTime = now;
}

显示内容
- 在浏览器中显示生成内容
- 自动滚动到底部

阶段 4：工具调用（可选）

调用工具
- Agent 判断需要调用代码解释器
- 调用工具接口
执行代码
- 代码解释器执行 Python 代码
- 使用 NumPy/Pandas 进行计算
返回结果
- 返回计算结果
- 包含执行输出和错误信息
继续生成
- Agent 继续生成内容
- 将工具结果整合到响应中

阶段 5：流式结束

Yield DONE
- Agent yield [DONE] 标记
- 表示流式传输结束
SSE 封装
- 后端封装为 SSE 格式
```
data: [DONE]
```
SSE 推送
- 通过 SSE 流式推送到前端
- 最后一次推送
读取数据
- JavaScript 读取数据
- 检测到 [DONE] 标记

解析标记

解析 [DONE] 标记


if (data === '[DONE]') {
    isComplete = true;
    break;
}

流式完成
- 流式传输完成
- 退出读取循环

最终渲染

进行最终的完整渲染


renderCompleteContent(currentMessageElement, accumulatedText);

显示结果
- 在浏览器中显示完整结果
- 包含 Markdown、数学公式和代码高亮

SSE 关键技术点

1. SSE 格式规范


data: {"content": "内容片段"}
data: {"content": "更多内容"}
data: [DONE]

每行以 data: 开头
数据为 JSON 格式
最后发送 [DONE] 表示结束

2. 响应头设置


Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

text/event-stream：SSE 专用媒体类型
no-cache：禁用缓存
keep-alive：保持长连接

3. 前端读取流程


const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value, { stream: true });
    buffer += chunk;
    
    const lines = buffer.split('\n');
    buffer = lines.pop() || '';
    
    for (const line of lines) {
        if (line.startsWith('data: ')) {
            const data = line.slice(6).trim();
            // 处理数据
        }
    }
}

4. 缓冲区管理

使用缓冲区处理不完整的行
按行分割，保留最后一个不完整的行
避免数据丢失

5. 性能优化

定期更新预览（每 200ms）
避免频繁渲染
自动滚动到底部
使用节流策略减少渲染次数

6. 错误处理


try {
    const response = await fetch('/api/openai/v1/chat/completions', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(requestBody)
    });
    
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    // 处理流式数据
} catch (error) {
    console.error('请求失败:', error);
    // 显示错误信息
}

SSE vs WebSocket 对比

特性	SSE	WebSocket
通信方向	单向（服务器 → 客户端）	双向
协议	HTTP	HTTP + WebSocket
连接保持	长连接	长连接
数据格式	文本（event-stream）	文本/二进制
浏览器支持	广泛支持	广泛支持
适用场景	实时推送、流式响应	实时双向通信

选择 SSE 的原因：

本场景只需要服务器向客户端推送数据
SSE 实现简单，无需额外协议
自动重连机制
与 HTTP 兼容性好

优势

实时性：实时展示计算过程，提升用户体验
低延迟：流式推送，无需等待完整响应
节省带宽：逐步传输，减少等待时间
易于实现：基于 HTTP 协议，无需额外配置
自动重连：浏览器自动重连机制
兼容性好：广泛支持，无需额外库

11. 使用示例

11.1 示例 1：函数求值

输入： "计算 f(x) = x³ - 2x² + 3x - 1 在 x=2 时的值"

Agent 处理过程：


def f(x):
    return x**3 - 2*x**2 + 3*x - 1

result = f(2)
print(f"f(2) = {result}")

输出： "f(2) = 5"

11.2 示例 2：方程求解

输入： "求解方程 2x² - 5x + 2 = 0"

输出： "方程的解为 x₁ = 2, x₂ = 0.5"

11.3 示例 3：数值积分

输入： "计算函数 f(x) = x² 在区间 [0, 1] 上的定积分"

Agent 处理过程：


import numpy as np

def f(x):
    return x**2

# 使用数值积分
x = np.linspace(0, 1, 10000)
integral = np.trapz(f(x), x)
print(f"定积分的值为: {integral}")

输出： "定积分的值为: 0.3333"

11.4 示例 4：矩阵运算

输入： "计算矩阵 A = [[1, 2], [3, 4]] 和 B = [[5, 6], [7, 8]] 的乘积"

Agent 处理过程：


import numpy as np

A = np.array([[1, 2], [3, 4]])
B = np.array([[5, 6], [7, 8]])

result = np.dot(A, B)
print("矩阵乘积:")
print(result)

输出：


矩阵乘积:
[[19 22]
 [43 50]]

11.5 示例 5：统计分析

输入： "计算数据集 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 的平均值、中位数和标准差"

Agent 处理过程：


import numpy as np

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

mean = np.mean(data)
median = np.median(data)
std = np.std(data)

print(f"平均值: {mean}")
print(f"中位数: {median}")
print(f"标准差: {std}")

输出：


平均值: 5.5
中位数: 5.5
标准差: 2.872

11.6 示例 6：函数极值

输入： "求函数 f(x) = x³ - 3x² + 2 的极值"

Agent 处理过程：


import numpy as np

def f(x):
    return x**3 - 3*x**2 + 2

def df(x):
    return 3*x**2 - 6*x

# 找到导数为零的点
roots = np.roots([3, -6, 0])
critical_points = [root.real for root in roots if abs(root.imag) < 1e-10]

for x in critical_points:
    y = f(x)
    second_derivative = 6*x - 6
    if second_derivative > 0:
        print(f"极小值点: x = {x:.4f}, f(x) = {y:.4f}")
    else:
        print(f"极大值点: x = {x:.4f}, f(x) = {y:.4f}")

输出：


极大值点: x = 0.0000, f(x) = 2.0000
极小值点: x = 2.0000, f(x) = -2.0000

12. 常见问题

12.1 使用问题

Q: 如何提高计算准确性？
A: 选择更强大的模型（如 qwen3-max），并将温度参数设置为较低值（0-0.3）。

Q: 遇到计算超时怎么办？
A: 在控制台增加超时时间设置，或将复杂问题拆解为多个简单步骤。

Q: 支持哪些数学函数？
A: 支持 Python 标准库中的所有数学函数，包括三角函数、对数、指数等。在代码解释器中还可以使用 NumPy 和 Pandas 的所有功能。

Q: 如何处理复杂的数学表达式？
A: 将复杂问题拆解为多个步骤，或者使用更明确的描述。例如，不要只说"求解这个方程"，而是说"求解方程 x³ - 2x² + x - 1 = 0 的所有实数根"。

12.2 技术问题

Q: 前端无法连接到后端怎么办？
A: 检查 BACKEND_URL 环境变量是否正确配置，确保后端服务正常运行。

Q: 数学公式渲染不正常怎么办？
A: 检查 KaTeX CDN 是否可访问，确保网络连接正常。

Q: 代码执行结果不显示怎么办？
A: 检查代码解释器沙箱是否正常启动，查看后端日志获取错误信息。

12.3 部署问题

Q: 部署失败怎么办？
A: 检查阿里云凭证是否正确配置，确保有足够的权限和资源配额。

Q: 如何更新应用？
A: 修改代码后，重新执行 s deploy 命令即可更新应用。

Q: 如何查看应用日志？
A: 在阿里云函数计算控制台中查看日志，或使用 s logs 命令。

12.4 注意事项

确保数学表达式语法正确
复杂计算建议分步骤描述
定期检查代码解释器工具状态
注意函数计算的超时限制
合理设置并发数，避免资源浪费

13. 贡献指南

我们欢迎任何形式的贡献！

13.1 如何贡献

贡献流程说明

步骤详解：

Fork 项目
- 在 GitHub 上 Fork 本项目到个人仓库
- 访问项目页面，点击右上角的 "Fork" 按钮
- 等待 Fork 完成
创建特性分支
- 克隆 Fork 的仓库到本地
```
git clone https://github.com/your-username/math-expert.git
cd math-expert
```
- 创建新的特性分支
```
git checkout -b feature/AmazingFeature
```
- 分支命名规范：feature/功能描述 或 fix/问题描述
开发修改
- 进行代码修改或文档更新
- 遵循代码规范（PEP 8、ES6+）
- 添加必要的注释和文档
- 编写测试用例
- 确保代码通过测试
提交更改
- 添加修改的文件
```
git add .
```
- 提交更改
```
git commit -m 'Add some AmazingFeature'
```
- 提交信息规范：
  - 简洁明了，描述修改内容
  - 使用英文，首字母大写
  - 示例：feat: 添加矩阵计算功能、fix: 修复公式渲染错误
推送到分支
- 推送分支到远程仓库
```
git push origin feature/AmazingFeature
```
开启 Pull Request
- 在 GitHub 上创建 Pull Request
- 选择源分支（feature/AmazingFeature）和目标分支（main）
- 详细描述修改内容：
  - 修改的目的和背景
  - 修改的具体内容
  - 测试结果和验证方法
  - 相关的 Issue 编号（如有）
代码审查
- 维护者会审查你的代码
- 可能会提出修改建议或问题
- 及时响应审查意见
- 根据反馈进行修改
合并代码
- 审查通过后，维护者会合并代码
- 你的贡献将被包含在主分支中
- 更新贡献者列表