feat: 增加 FastAPI 服务接口及外部调用文档

这个提交包含在:
2026-04-04 11:57:44 +08:00
父节点 2c07cb8de7
当前提交 d13ff4e3fe
共有 3 个文件被更改,包括 282 次插入 和 0 次删除

123
docs/API_REFERENCE.md 普通文件
查看文件

@ -0,0 +1,123 @@
# API 接口文档
为满足物理竞赛声速测量实验从外部网页直连问答系统的需求,我们已经提供了基于 FastAPI 构建的本地 HTTP 接口 `api_server.py`。
## 启动服务
在终端中执行以下命令:
```bash
pip install -r requirements.txt
uvicorn api_server:app --reload
```
服务启动后,将在 `http://127.0.0.1:8000` 提供服务。
> **提示**:你也可以直接访问 `http://127.0.0.1:8000/docs` 查看并使用可交互的 Swagger UI 在线调试文档。
---
## 核心会话接口
无论是一次性等待结果(传统 Request),还是逐字流式打字机输出(SSE 流),都共用同一个路由 `/api/chat`,通过在 `body` 中注入 `stream` 控制响应类型。
### 1. `POST /api/chat`
**请求地址**:`http://127.0.0.1:8000/api/chat`
**Content-Type**:`application/json`
**请求参数 (Body)**:
```json
{
"teacher_type": "question",
"messages": [
{
"role": "user",
"content": "老师,我不明白实验里的相位差怎么找?"
}
],
"stream": false
}
```
* `teacher_type`:必填。可选值为 `question`(疑问解答老师), `grader`(答题评估老师), `data_eval`(数据评价老师)。
* `messages`:必填。存放与用户的历史对话列表。
* `stream`: 可选。是否开启流式输出 (打字机效果)。默认为 `false`。
### 2. 返回模式 1:普通阻塞调用(`stream: false`)
**返回结果 (200 OK)**:
```json
{
"response": "同学你好!要找到正确的相位差,你需要重点关注示波器上的..."
}
```
**前端示例代码 (JavaScript)**:
```javascript
async function sendChatMessage() {
const response = await fetch('http://127.0.0.1:8000/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
teacher_type: 'question',
messages: [{ role: 'user', content: '驻波法有哪些关键注意点?' }],
stream: false
})
});
const data = await response.json();
console.log(data.response); // 一次性输出完整回复
}
```
### 3. 返回模式 2:SSE流式调用(`stream: true`)
如果传递 `stream: true`,接口将返回 `text/event-stream` 格式的数据。
**流式返回片断示例**:
```text
data: {"content": "同"}
data: {"content": "学"}
data: {"content": "你"}
data: {"content": "好"}
data: [DONE]
```
**前端打字机效果示例代码 (JavaScript)**:
```javascript
async function sendStreamingMessage() {
const response = await fetch('http://127.0.0.1:8000/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
teacher_type: 'question',
messages: [{ role: 'user', content: '驻波法有哪些关键注意点?' }],
stream: true
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
let done = false;
while (!done) {
const { value, done: readerDone } = await reader.read();
done = readerDone;
if (value) {
const chunk = decoder.decode(value, { stream: true });
const lines = chunk.split('\n');
for (const line of lines) {
if (line.startsWith('data: ') && line !== 'data: [DONE]') {
const payload = JSON.parse(line.slice(6));
if (payload.content) {
// 此处拼接字符到 UI 上
document.getElementById('chat-box').innerHTML += payload.content;
}
}
}
}
}
}
```
## 注意事项
- **跨域安全 (CORS)**:本服务端代码默认允许所有来源 (`allow_origins=["*"]`) 的跨域调用。若要部署至生产线上网络,请修改 `api_server.py` 内的相关策略保障安全。
- **依赖说明**:`api_server.py` 本身未经过 AutoGen 复杂的工具编排调用,而是抽调了您整理出的 Prompt/Tasks 标准化预设直接通过 OpenAI Async 引擎封装为最稳定、带响应流式的 Http 接口。这通常更符合 Web UI 聊天系统的构建诉求。