feat: 增加 FastAPI 服务接口及外部调用文档
这个提交包含在:
123
docs/API_REFERENCE.md
普通文件
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 聊天系统的构建诉求。
|
||||
在新工单中引用
屏蔽一个用户