Skip to content

About

码上面试平台 Python 重写版(FastAPI),API 契约与原 Java 项目一致

Resources

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

ai-meeting

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。

前端 Demo

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 head

scripts/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。

Skill 业务知识体系

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.py

CI 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 哈希;旧明文密码在首次成功登录时自动升级。

About

码上面试平台 Python 重写版(FastAPI),API 契约与原 Java 项目一致

Resources

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages