Daniel/Airtep

Fork 0

Files

Daniel 84f8be7c0e feat: 初始化零工后端代码

2026-04-01 14:19:25 +08:00

5.6 KiB

Raw Blame History

Gig POC README

项目目标

本项目实现一个“灵活用工最小 POC 内核系统”，围绕岗位理解、工人理解、LightRAG 检索、匹配排序和推荐解释构建完整闭环。

技术栈

后端：Python 3.11、FastAPI、Pydantic、SQLAlchemy、Uvicorn
数据层：PostgreSQL 16、Qdrant
前端：React 19、Vite 6
部署：Docker Compose
模型接入：OpenAI 兼容 LLM 接口，可选开启；默认启用本地规则兜底，推荐模型默认值为 gpt-5.4

目录结构

/gig-poc
  /apps
    /web
    /api
  /packages
    /shared-types
    /prompts
    /sample-data
  /infrastructure
    docker-compose.yml
    docker-compose.prod.yml
    /sql
    /scripts
  /docs
    README.md
    API.md
    ARCHITECTURE.md
    DEMO.md

环境变量说明

DATABASE_URL：PostgreSQL 连接串
QDRANT_URL：Qdrant 服务地址
LLM_ENABLED：是否启用外部 LLM 抽取
LLM_BASE_URL：OpenAI 兼容接口地址
LLM_API_KEY：模型服务密钥
LLM_MODEL：模型名称
LLM_FALLBACK_BASE_URLS：LLM 备用端点列表（JSON 数组）
AI_RATE_LIMIT_PER_MINUTE：AI 请求每分钟限流阈值
AI_CIRCUIT_BREAKER_FAIL_THRESHOLD：熔断触发失败次数
AI_CIRCUIT_BREAKER_COOLDOWN_SECONDS：熔断冷却秒数
EMBEDDING_ENABLED：是否启用正式 embedding
EMBEDDING_BACKEND：hash 或 openai_compatible
EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL：embedding 配置
INGEST_ASYNC_ENABLED：是否启用异步入库队列
INGEST_QUEUE_MAX_SIZE：异步队列最大长度
MATCH_CACHE_ENABLED：是否启用匹配缓存
MATCH_CACHE_TTL_SECONDS：匹配缓存 TTL（秒）
QUERY_CACHE_ENABLED：是否启用查询缓存（列表与详情）
QUERY_CACHE_TTL_SECONDS：查询缓存 TTL（秒）
CACHE_BACKEND：缓存后端，memory 或 redis
REDIS_URL：Redis 连接串
APP_RATE_LIMIT_PER_MINUTE：全局请求限流阈值
APP_CIRCUIT_BREAKER_*：全局熔断参数（错误率、窗口、冷却）
ALERT_WEBHOOK_URL：告警 webhook（可选）
DATABASE_POOL_SIZE / DATABASE_MAX_OVERFLOW / DATABASE_POOL_TIMEOUT：数据库连接池参数
MATCH_ASYNC_ENABLED：是否启用异步匹配队列
MATCH_QUEUE_MAX_SIZE：异步匹配队列最大长度

启动方式

cd gig-poc
sh infrastructure/scripts/dev-up.sh
默认会自动执行：
- 健康检查 + bootstrap
- 一键闭环验收脚本（抽取 -> 入库 -> 匹配 -> 解释）
- 导出 docs/openapi.json
可选开启容量基线压测：
- RUN_BASELINE_ON_UP=true sh infrastructure/scripts/dev-up.sh

生产环境启动/停止

启动：sh infrastructure/scripts/prod-up.sh
停止：sh infrastructure/scripts/prod-down.sh
可选环境变量：
- WEB_PORT（默认 80）
- API_PORT（默认 8000）
- BOOTSTRAP_ON_UP（默认 true，可设置为 false 跳过样本初始化）

样本导入方式

dev-up.sh 会在健康检查通过后自动触发 /poc/ingest/bootstrap，导入 100 岗位、300 工人和词表。

API 地址

http://127.0.0.1:8000
OpenAPI：http://127.0.0.1:8000/docs
OpenAPI JSON 导出：sh infrastructure/scripts/export-openapi.sh
OpenAPI 固化（离线生成并入库）：sh infrastructure/scripts/freeze-openapi.sh
AI 观测接口：GET /poc/ops/ai/metrics
系统观测接口：GET /poc/ops/system/metrics
异步匹配接口：POST /poc/match/workers/async、POST /poc/match/jobs/async、GET /poc/match/queue/{task_id}

前端访问地址

http://127.0.0.1:5173

演示路径

打开岗位测试页，输入岗位描述并抽取
点击入库并匹配工人
打开工人测试页，输入工人描述并抽取
点击入库并匹配岗位
在系统状态页执行健康检查和样本导入

一键闭环验收

cd gig-poc
sh infrastructure/scripts/acceptance-e2e.sh

该脚本会自动验证两条链路：

岗位文本抽取 -> 岗位入库 -> 岗位匹配工人 -> 匹配解释
工人文本抽取 -> 工人入库 -> 工人匹配岗位 -> 匹配解释

容量基线压测

cd gig-poc
sh infrastructure/scripts/load-baseline.sh

输出文件：

docs/CAPACITY_BASELINE.md

可选参数：

TOTAL_REQUESTS（默认 400）
CONCURRENCY（默认 40）

规模化建议（上线前）

应用层：开启多实例部署（建议至少 2 个 API 实例）并接入负载均衡。
数据层：PostgreSQL、Qdrant 使用托管或主从/集群形态，避免单点。
链路层：优先走异步入库接口（/poc/ingest/*/async）吸收突发写流量。
匹配层：高峰请求优先走异步匹配接口（/poc/match/*/async）做削峰。
观测层：接入 /poc/ops/system/metrics 与 /poc/ops/ai/metrics 到监控告警系统。
发布层：每次发布前更新 docs/openapi.json 与 docs/CAPACITY_BASELINE.md。

K8s 扩容部署（基础模板）

目录：infrastructure/k8s

cd gig-poc
kubectl apply -k infrastructure/k8s

包含资源：

API Deployment + Service + HPA（默认 3~20 副本）
Web Deployment + Service + HPA（默认 2~10 副本）
Redis Deployment + Service
Ingress 示例路由

详细策略说明见：docs/SCALING.md

已实现范围

岗位抽取
工人抽取
JobCard / WorkerCard / MatchResult 统一 schema
样本数据 bootstrap
LightRAG 风格向量检索适配层
两阶段召回与排序
推荐理由生成
Web 控制台
Docker Compose 本地与生产部署

未实现范围

裂变、支付、合同、工时、薪资结算
权限系统与复杂后台
大规模并发优化

5.6 KiB Raw Blame History Unescape Escape