Airtep/gig-poc/docs

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：异步匹配队列最大长度

启动方式

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

演示路径

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

一键闭环验收

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 本地与生产部署

未实现范围

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