166 lines
5.6 KiB
Markdown
166 lines
5.6 KiB
Markdown
# 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`
|
||
|
||
## 目录结构
|
||
```text
|
||
/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. 在系统状态页执行健康检查和样本导入
|
||
|
||
## 一键闭环验收
|
||
```bash
|
||
cd gig-poc
|
||
sh infrastructure/scripts/acceptance-e2e.sh
|
||
```
|
||
|
||
该脚本会自动验证两条链路：
|
||
- 岗位文本抽取 -> 岗位入库 -> 岗位匹配工人 -> 匹配解释
|
||
- 工人文本抽取 -> 工人入库 -> 工人匹配岗位 -> 匹配解释
|
||
|
||
## 容量基线压测
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
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 本地与生产部署
|
||
|
||
## 未实现范围
|
||
- 裂变、支付、合同、工时、薪资结算
|
||
- 权限系统与复杂后台
|
||
- 大规模并发优化
|