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

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

154
api_server.py 普通文件
查看文件

@ -0,0 +1,154 @@
import os
import json
import asyncio
from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import List, Dict, Any, Optional
from dotenv import load_dotenv
# 加载环境变量
load_dotenv()
# 尝试导入 autogen
try:
from autogen_agentchat.agents import AssistantAgent
except ImportError:
try:
from autogen import AssistantAgent
except ImportError:
pass
app = FastAPI(
title="物理竞赛声速测量实验预习问答 API",
description="提供三种辅助老师角色的 AI 回答接口",
version="1.0.0"
)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
AGENTS_CONFIG = {
"question": {
"persona": "personas/qa-teacher.md",
"task": "tasks/answer-questions.md",
"data": ["data/physics-glossary.md"]
},
"grader": {
"persona": "personas/grader-teacher.md",
"task": "tasks/grade-answers.md",
"data": ["data/physics-glossary.md", "data/grading-standards.md"]
},
"data_eval": {
"persona": "personas/data-eval-teacher.md",
"task": "tasks/evaluate-data.md",
"data": ["data/physics-glossary.md", "data/grading-standards.md"]
}
}
def load_file(filepath):
full_path = os.path.join(BASE_DIR, filepath)
if os.path.exists(full_path):
with open(full_path, "r", encoding="utf-8") as f:
return f.read()
return ""
def build_system_message(teacher_type):
config = AGENTS_CONFIG.get(teacher_type)
if not config:
raise ValueError("Unknown teacher type")
sys_msg_parts = []
# 1. 角色设定
persona_content = load_file(config["persona"])
if persona_content: sys_msg_parts.append(persona_content)
# 2. 任务要求
task_content = load_file(config["task"])
if task_content: sys_msg_parts.append(task_content)
# 3. 补充领域知识
if "data" in config:
sys_msg_parts.append("## 附录:专业词汇与知识库")
for data_file in config["data"]:
data_content = load_file(data_file)
if data_content: sys_msg_parts.append(data_content)
return "\n\n---\n\n".join(sys_msg_parts)
class Message(BaseModel):
role: str
content: str
class ChatRequest(BaseModel):
teacher_type: str # 'question', 'grader', 'data_eval'
messages: List[Message]
stream: Optional[bool] = False
@app.post("/api/chat")
async def chat_endpoint(req: ChatRequest):
if req.teacher_type not in AGENTS_CONFIG:
raise HTTPException(status_dir=400, detail="Invalid teacher_type. Choose from 'question', 'grader', 'data_eval'.")
system_msg = build_system_message(req.teacher_type)
# 这里我们使用原生的 OpenAI/DeepSeek API 接口进行调用,以便更容易控制流式响应
# 如果基于 autogen 的代理进行复杂工作流,可以替换为 autogen 的调用。
# 这里以对接通用 OpenAI 兼容接口作为示例
from openai import AsyncOpenAI
api_key = os.getenv("OPENAI_API_KEY")
base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
model_name = os.getenv("MODEL_NAME", "gpt-4o-mini")
if not api_key:
raise HTTPException(status_code=500, detail="OPENAI_API_KEY environment variable not set")
client = AsyncOpenAI(api_key=api_key, base_url=base_url)
messages = [{"role": "system", "content": system_msg}]
for msg in req.messages:
messages.append({"role": msg.role, "content": msg.content})
if req.stream:
async def event_generator():
try:
stream = await client.chat.completions.create(
model=model_name,
messages=messages,
stream=True
)
async for chunk in stream:
if chunk.choices[0].delta.content:
yield f"data: {json.dumps({'content': chunk.choices[0].delta.content}, ensure_ascii=False)}\n\n"
yield "data: [DONE]\n\n"
except Exception as e:
yield f"data: {json.dumps({'error': str(e)})}\n\n"
return StreamingResponse(event_generator(), media_type="text/event-stream")
else:
try:
response = await client.chat.completions.create(
model=model_name,
messages=messages,
stream=False
)
return {"response": response.choices[0].message.content}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
if __name__ == "__main__":
import uvicorn
# uvicorn.run(app, host="0.0.0.0", port=8000)
uvicorn.run("api_server:app", host="0.0.0.0", port=8000, reload=True)

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 聊天系统的构建诉求。

5
requirements.txt 普通文件
查看文件

@ -0,0 +1,5 @@
fastapi
uvicorn
pyautogen
python-dotenv
sse-starlette