# AI 网关服务

> 版本：1.0（P5 完整实现）
> 端口：HTTP 3008 + gRPC 50058
> 定位：D6 智能洞察领域 · 生成子域（Python/FastAPI，严格无状态）

## 职责

统一封装 LLM 调用（多模型路由 + 故障切换 + 熔断 + 限流 + 成本控制），提供：
- **聊天**：非流式 + SSE 流式
- **题目生成**：非流式 + 流式 + 评估三道防线（RuleValidator + LLMJudge + QualityGate）
- **表达优化**：文字清晰度/简洁度/语气优化
- **备课工作流**：4 步编排（分析学情 → 推荐知识点 → 生成题目 → 教师审核入库）

通过 gRPC 查询 content 题库与 data-ana 学情数据。通过 Kafka 发布 AIUsageEvent 供 data-ana 统计。

## 技术栈

- Python 3.12 + FastAPI 0.115
- Pydantic 2 + pydantic-settings（12-factor 配置）
- grpc.aio（gRPC server 8 RPC + client 拦截器）
- aiokafka（用量事件发布，事务性 + 幂等，派生数据豁免 Outbox）
- Jinja2 + YAML（Prompt 模板渲染）
- redis（限流令牌桶 + 用量记录 + 工作流状态存储）
- OpenTelemetry（HTTP + gRPC 链路追踪）
- prometheus-client + structlog（指标 + 结构化日志）

## 架构分层

```
HTTP 端点（/v1/ai 前缀，ActionState 信封）
    ↓
PermissionGuard（权限校验）→ RateLimiter（三维度令牌桶）
    ↓
Service 层（ChatService / QuestionService / ExpressionService / LessonPlanWorkflowService）
    ↓
LLM ProviderFailoverChain（4 适配器 + CircuitBreaker）
    ↓
LLM Provider（OpenAI / Anthropic / Baichuan / LocalOllama）

gRPC server（端口 50058，8 RPC，interceptor 链）
    ↓
AiServicer（proto ↔ domain 模型转换）
    ↓
Service 层（同 HTTP）

备课工作流：FastAPI BackgroundTasks + Redis 状态存储（24h TTL）
安全层：PIIRedactor + InputSanitizer + OutputModerator
用量：UsageRecorder（Redis）→ KafkaProducer → edu.ai.usage topic
```

## 开发

```bash
# 安装依赖
uv sync

# 启动开发服务（dev_mode=true 跳过 OTel exporter）
DEV_MODE=true uv run uvicorn src.ai.main:app --reload --port 3008

# Lint
uv run ruff check src/

# 测试
uv run pytest
```

## HTTP API

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | /healthz | — | liveness |
| GET | /readyz | — | readiness（含 LLM/gRPC/Provider 状态） |
| GET | /metrics | — | Prometheus 指标 |
| POST | /v1/ai/chat | ai:chat | 非流式聊天 |
| POST | /v1/ai/chat/stream | ai:chat | 流式聊天（SSE） |
| POST | /v1/ai/generate/question | ai:question:generate | 生成题目 |
| POST | /v1/ai/generate/question/stream | ai:question:generate | 流式生成题目（SSE） |
| POST | /v1/ai/optimize/expression | ai:expression:optimize | 优化表达 |
| POST | /v1/ai/lesson-plan/generate | ai:lesson:generate | 启动备课工作流 |
| GET | /v1/ai/lesson-plan/status/{workflow_id} | — | 查询工作流状态 |
| POST | /v1/ai/lesson-plan/confirm/{workflow_id} | ai:lesson:confirm | 教师确认入库 |

所有业务响应统一使用 ActionState 信封：`{success, data, error:{code, message, details?, traceId?}}`

降级采用方案 B（总裁裁决 §2.6）：`success=true + error=null + data 内 degraded=true + degraded_reason`

## gRPC API（端口 50058，8 RPC）

| RPC | 请求 | 响应 |
|-----|------|------|
| Chat | ChatRequest | ChatResponse |
| StreamChat | ChatRequest | stream ChatChunk |
| GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion |
| StreamGenerateQuestion | GenerateQuestionRequest | stream GeneratedQuestionChunk |
| OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression |
| GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlanResponse |
| GetLessonPlanStatus | GetLessonPlanStatusRequest | LessonPlanStatus |
| ConfirmLessonPlan | ConfirmLessonPlanRequest | ConfirmResult |

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| http_port | 3008 | HTTP 端口 |
| grpc_port | 50058 | gRPC 端口 |
| dev_mode | false | 开发模式（跳过 OTel + 权限校验） |
| openai_api_key | — | OpenAI API 密钥 |
| anthropic_api_key | — | Anthropic API 密钥 |
| baichuan_api_key | — | 百川 API 密钥 |
| ollama_base_url | — | 本地 Ollama 地址 |
| llm_provider_priority | openai,anthropic,baichuan,local_ollama | Provider 故障切换顺序 |
| redis_url | redis://localhost:6379/0 | Redis 连接 |
| kafka_bootstrap_servers | localhost:9092 | Kafka 连接 |
| kafka_ai_usage_topic | edu.ai.usage | 用量事件 topic |
| otel_endpoint | http://localhost:4318 | OpenTelemetry OTLP 端点 |

## 限流（三维度）

| 维度 | 限制 | 算法 |
|------|------|------|
| user | 10 req/min | Redis Lua 令牌桶 |
| IP | 30 req/min | Redis Lua 令牌桶 |
| school | 100 req/min | Redis Lua 令牌桶 |

Redis 不可用时降级放行（记录警告）。

## 错误码

前缀 `AI_*`，完整 21 个错误码见 [02-architecture-design.md §6.2](docs/02-architecture-design.md)。