feat: 增加 FastAPI 服务接口及外部调用文档
这个提交包含在:
154
api_server.py
普通文件
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
普通文件
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
普通文件
5
requirements.txt
普通文件
@ -0,0 +1,5 @@
|
||||
fastapi
|
||||
uvicorn
|
||||
pyautogen
|
||||
python-dotenv
|
||||
sse-starlette
|
||||
在新工单中引用
屏蔽一个用户