AI 模拟面试平台后端服务。围绕「上传简历 → AI 出题 → 语音/文字答题 → 评分与追问 → 神态分析 → 复盘报告」
的完整面试链路,同时提供通用 AI 会话、智能体会话与实时语音能力,对外暴露 73 个 HTTP / WebSocket 接口
(前缀 /api/xunzhi/v1)。
| 模块 | 端点 | 能力 |
|---|---|---|
app/user + app/auth |
11 | 注册(布隆 + 分布式锁 + 唯一索引三层防重)、登录登出、用户名查重、用户分页与管理员权限 |
app/ai |
17 | 通用 AI 会话 CRUD、SSE 流式聊天、历史消息分页;AI 模型配置管理(启用/停用、选项列表) |
app/agent |
12 | 智能体会话与 SSE 聊天、会话历史、文件上传;智能体配置与标签管理;场景 → 智能体绑定底座 |
app/interview |
23 | 面试会话生命周期、简历出题、答题管线(评分 + 追问裁决 + 原子推进)、简历评分与预览、神态分析、雷达图报告、会话恢复 |
app/media |
9 | 讯飞实时 ASR(WebSocket 流式转写 + 分段增量去重)、服务端推送、长文本 TTS 两阶段任务 |
| 运维 | 1 | GET /actuator/health |
面试链路的核心工程能力:
- 状态机 + 乐观锁:
InterviewFlowState七字段存 Redis hash,所有迁移走 Lua CAS(version 不匹配整体失败), 不存在部分字段单独写入。 - 幂等 + 题级锁 + 锁后二次校验:同一 requestId 重放直接回放结果;排队期间题号或 version 被推进则拒绝, 避免同一题被评两次分。
- 分布式 single-flight:出题、评分、追问等重调用同会话同题只穿透一次,其余请求等待同一结果,含心跳租约与降级分支。
- 热冷快照 + 懒重水合:易变的 flow/分数与整场不变的题目载荷分两个 Mongo 集合,避免每答一题重写几十 KB 题目 JSON; Redis 运行态丢失时按「只写不覆盖、分数从轮次重算、写不了就抛」三原则重建。
- fail-closed 评分:AI 输出两级解析都失败时终止本次答题(不推进、不计分、记失败计数),不做静默降级。
- 补偿 outbox:轮次日志写失败入队,由独立进程
python -m app.interview.worker重放,不绑请求生命周期。
Python 3.12 / FastAPI / Pydantic v2 + pydantic-settings / SQLAlchemy 2.0 async + aiomysql / Alembic / PyMongo 异步客户端 / redis-py / sse-starlette / websockets / httpx;依赖与虚拟环境用 uv 管理, lint 用 ruff,测试用 pytest + pytest-asyncio。
外部依赖:讯飞星辰工作流(出题官 / 评分官 / 提问官 / 神态分析 / 通用智能体)、讯飞实时语音转写与长文本合成。
app/
├── main.py 路由注册、中间件装配、lifespan(布隆回灌 / 关停清理)
├── core/ 横切:config db locks rate_limit duplicate_submit middleware result exceptions seq
├── integrations/ 外部 HTTP 客户端(xingchen.py:SSE chat + upload_file)
├── auth/ token 签发校验、get_current_user 依赖
├── user/ 账号与注册布隆
├── ai/ 通用 AI 会话 + AI 配置
├── agent/ 智能体会话/文件/配置 + 场景绑定 resolver(全项目共用)
├── interview/ 面试全链路,含 flight/(single-flight)与 runtime/(快照水合)
└── media/ 实时 ASR、服务端推送、TTS
边界规则:app/core 不得 import 任何业务包;外部 HTTP 只经 app/integrations/;
场景 → 智能体解析只在 app/agent/resolver.py 一处。
存储职责:
| 存储 | 存什么 | 是否权威 |
|---|---|---|
| MySQL | 用户与权限、AI/智能体配置与标签、面试记录、上传文件资产 | 是(schema 由 Alembic 管) |
| MongoDB | AI / 智能体 / 面试三套会话与消息、运行态热冷快照、轮次归档 | 会话是;快照是派生数据 |
| Redis | 登录态、面试运行态(flow/题目/分数)、限流、分布式锁、幂等标记、注册布隆、补偿队列 | 面试运行态的权威源 |
中间件顺序(main.py 内 add 顺序 = 由内到外):流量风控 → RequestId → CORS,
因此 429 响应同样带 X-Request-Id 与 CORS 头。
# 1. 启动基础设施(MySQL/Mongo/Redis)
docker compose up -d mysql mongo redis
# 2. 安装依赖并执行数据库迁移
uv sync
uv run alembic upgrade head
# 3. 启动服务
uv run uvicorn app.main:app --reload --port 8080
# 4. 验证
curl http://127.0.0.1:8080/actuator/health交互式接口文档在 http://127.0.0.1:8080/docs。
frontend/ 是一个零构建的静态 SPA(vanilla JS + nginx,无 node_modules),覆盖四条核心链路:
| 页面 | 能力 |
|---|---|
| 登录 / 注册 | 布隆查重提示、注册即登录、登录态持久化 |
| 🎙️ AI 面试 | 创建会话 → 上传简历出题(简历评分 / 题库 / 作答建议)→ 答题评分与追问(支持语音作答)→ 雷达图复盘 / 简历预览 / 神态评估 |
| 💬 AI 会话 | 多模型会话管理、SSE 流式聊天(含 reasoning 思考过程)、AI 配置增删与启停、语音输入 + 回复朗读(TTS) |
| 🤖 智能体 | 会话创建、星辰工作流流式聊天(嵌套 JSON 自动可读化)、附件上传、语音输入 + 回复朗读(TTS) |
语音链路(参考原前端 AI-Meeting-Frontend 的实现参数对接 app/media):
- 实时转写(ASR):
js/asr.js麦克风采集 16kHz 单声道 PCM(int16,640 采样 = 40ms/帧), 经 WebSocket/api/xunzhi/v1/xunfei/audio-to-text/{userId}上行,转写快照实时显示、 停止后等待 final 定稿再追加进输入框。需浏览器麦克风权限(HTTPS 或 localhost)。 - 长文本合成(TTS):
js/tts.js调/xunfei/tts/synthesize,audioBase64转 Blob 播放。 - 两者共用讯飞凭证(代码默认值或
XUNFEI_*环境变量)。凭证返回11200 licc limit表示试用授权额度用尽,需更换有效凭证。
全容器方式一键起前后端:后端 http://127.0.0.1:8081,前端 http://127.0.0.1:8082。
nginx 同源反代 /api 到 app 容器(关 buffering 保 SSE 增量、支持 WebSocket 升级),浏览器侧无 CORS 问题。
docker compose up --build -d
# 打开 http://127.0.0.1:8082把 demo 环境数据(demo 账号 / 「通用智能体」绑定 / 兜底 AI 配置)灌进 docker 卷:
docker compose exec app uv run --no-dev python scripts/seed_agent_properties.py # 4 条面试官智能体
docker compose exec app uv run --no-dev python scripts/seed_demo_env.py # demo 账号等,幂等- demo 账号:
demo/demo123456(管理员)。 - 若 AI 会话聊天回复
Sorry, an error occurred...,是卷里 AI 配置的模型 key 失效: 在前端「AI 配置管理」里用真实 key 新增一条即可;面试官智能体由星辰工作流驱动, 凭证来自scripts/seed_agent_properties.py。 - 本地开发也可直接
python -m http.server -d frontend 5500静态托管,API 地址经同源反代之外的 方式(改frontend/js/api.js的API_BASE)指向 8080。
配置集中在 app/core/config.py 的 Settings(pydantic-settings),支持 .env 与环境变量覆盖,
字段与环境变量对照见 skills/xunzhi-ai-runtime/references/generated-config-index.md。
复制 .env.example 起步,常改的几组:
- 存储连接:
MYSQL_DSN/MONGO_URI/MONGO_DB/REDIS_URL - 场景智能体绑定:
XUNZHI_AGENT_*(值要和agent_properties.agent_name对得上) - 讯飞凭证:
XUNFEI_APP_ID/XUNFEI_API_KEY/XUNFEI_API_SECRET - 流量风控:
XUNZHI_AGENT_FLOW_LIMIT_ENABLE(默认开)与各桶配额,默认桶 20/1s、 面试读 15/1s、答题 8/1s、重调用 2/1s,另有 AI 叠加桶 6/1s - 注册布隆:
USER_BLOOM_CAPACITY/USER_BLOOM_FPP。改这两个值后必须删除 Redis 键userRegisterCachePenetrationBloomFilter,否则旧位图按新参数读位全盘错位
MySQL schema 的唯一来源是 Alembic revision。新增或修改 SQLAlchemy 模型时,提交对应的 migration:
uv run alembic revision --autogenerate -m "describe_change"
uv run alembic upgrade headscripts/sql 仅保留为旧环境参考,不由 Docker Compose 执行,也不是增量迁移机制。
已由 scripts/sql 初始化过的 MySQL volume,先核对现有表结构与 0001_initial_schema 一致,
再执行一次 uv run alembic stamp 20260802_0001 建立版本基线,不要直接 upgrade head。
uv run pytest -m "not integration" # 30 个文件 / 473 个用例,无需真实基础设施
uv run ruff check .集成用例(-m integration)需要本地 8080 服务与真实 MySQL/Mongo/Redis,CI 跳过。
CI 三个 job:ruff lint、pytest(起 MySQL/Mongo/Redis service 容器真跑)、docs 抽取器 --check。
skills/ 下 9 个域(repo-map / interview / agent / media / ai-runtime / auth-user /
business-dictionary / change-playbook / debug-playbook)是面向 Code Agent 的模块化业务知识,
共 58 篇;其中 references/generated-*.md 由 4 个抽取器从源码生成。
入口是 skills/xunzhi-repo-map:先按需求路由到主域,再下钻对应 references。
改接口 / 配置 / 场景绑定 / 工作流后重新生成:
uv run python skills/xunzhi-repo-map/scripts/extract_api_index.py
uv run python skills/xunzhi-ai-runtime/scripts/extract_config_index.py
uv run python skills/xunzhi-agent-domain/scripts/extract_agent_scene_map.py
uv run python skills/xunzhi-interview-domain/scripts/extract_workflow_contracts.pyCI docs job 以 --check 模式校验生成物与 docs/API.md 的路由覆盖,不一致即失败。
docs/workflow/*.yml 是星辰平台导出的工作流契约快照(运行时不读,仅作契约文档)。
- 统一响应体
{code, message, data, requestId},业务异常一律 HTTP 200 + 非0的 code; 限流是唯一返回 HTTP 429 的场景。 GET /users/has-username的语义是 true = 用户名已存在,纯布隆判断不查库。- 注册冲突(布隆命中 / 抢锁失败 / 唯一索引冲突)统一返回
A000111。 - 题号格式
\d+(主问题)或\d+-F\d+(追问),追问不计入总分。 - SSE 聊天末尾补发
event: end / data: [DONE],前端据此收流。 - 逐条接口参数与响应见
docs/API.md。
- 密钥出口:
agent-properties查询响应中的apiKey/apiSecret已按与ai-properties相同的首尾掩码规则脱敏,内部存储和调用仍使用原始值。 - WebSocket 音频队列:音频队列已限制为 64 帧;消费端阻塞时拒绝后续帧并结束转写,避免会话时长导致内存无限增长。
- 连接注册表:本地连接表保留用于快速投递,同时通过 Redis Pub/Sub 广播到其他实例;Redis 不可用时继续提供本地推送。
- 登录密码存储:注册和改密使用带随机盐的 PBKDF2-SHA256 哈希;旧明文密码在首次成功登录时自动升级。