76 lines
2.9 KiB
Python
76 lines
2.9 KiB
Python
"""AI-backed sentence explanations for the mobile clients."""
|
|
|
|
from dataclasses import dataclass
|
|
|
|
import requests
|
|
|
|
|
|
class AITutorError(RuntimeError):
|
|
"""Raised when the configured AI service cannot answer a request."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class AITutor:
|
|
endpoint: str
|
|
api_key: str
|
|
model: str
|
|
timeout_seconds: float
|
|
|
|
@property
|
|
def available(self) -> bool:
|
|
return bool(self.endpoint and self.model)
|
|
|
|
def explain(
|
|
self,
|
|
sentence_text: str,
|
|
*,
|
|
course_title: str = "",
|
|
sentence_index: int | None = None,
|
|
language: str = "",
|
|
) -> str:
|
|
if not self.available:
|
|
raise AITutorError("AI explanation is not configured.")
|
|
|
|
context = course_title.strip() or "口语训练课程"
|
|
position = f"第 {sentence_index + 1} 句" if sentence_index is not None else "当前句子"
|
|
language_note = f"句子语言：{language.strip()}。" if language.strip() else ""
|
|
system_prompt = (
|
|
"你是一位耐心的外语口语老师。请用简体中文讲解用户提供的影视/课程句子。"
|
|
"先给出自然的中文翻译，再解释关键词、常用搭配或语法要点，并简要说明这句话适合怎样跟读。"
|
|
"回答使用简明清晰的分段短文，总长度不超过 300 字，不要编造视频里没有的信息。"
|
|
)
|
|
user_prompt = (
|
|
f"课程：{context}\n位置：{position}\n{language_note}句子：{sentence_text}"
|
|
)
|
|
headers = {"Content-Type": "application/json"}
|
|
if self.api_key:
|
|
headers["Authorization"] = f"Bearer {self.api_key}"
|
|
try:
|
|
response = requests.post(
|
|
self.endpoint,
|
|
headers=headers,
|
|
json={
|
|
"model": self.model,
|
|
"messages": [
|
|
{"role": "system", "content": system_prompt},
|
|
{"role": "user", "content": user_prompt},
|
|
],
|
|
"temperature": 0.3,
|
|
"stream": False,
|
|
},
|
|
timeout=self.timeout_seconds,
|
|
)
|
|
except requests.RequestException as exc:
|
|
raise AITutorError("AI service request failed.") from exc
|
|
|
|
if response.status_code < 200 or response.status_code >= 300:
|
|
raise AITutorError(f"AI service returned HTTP {response.status_code}.")
|
|
try:
|
|
body = response.json()
|
|
explanation = body["choices"][0]["message"]["content"]
|
|
except (KeyError, IndexError, TypeError, ValueError) as exc:
|
|
raise AITutorError("AI service returned an unexpected response.") from exc
|
|
if not isinstance(explanation, str) or not explanation.strip():
|
|
raise AITutorError("AI service returned an empty explanation.")
|
|
return explanation.strip()
|