You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
306 lines
10 KiB
306 lines
10 KiB
# Face Recognition Service - Sequence Diagrams
|
|
|
|
## 1. Face Registration Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant RegisterUC as RegisterFaceUseCase
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant S3 as S3ObjectStorage
|
|
participant TaskPub as TaskPublisher
|
|
participant MQ as RabbitMQ
|
|
participant StatusRepo as TaskStatusRepository
|
|
participant Worker as FaceWorker
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant FaceRepo as MongoDBFaceRepository
|
|
participant VectorStore as ChromaDBVectorStore
|
|
participant MongoDB as MongoDB Database
|
|
participant ChromaDB as ChromaDB Vector DB
|
|
|
|
User->>GradioUI: Upload images + username
|
|
GradioUI->>RegisterUC: execute(username, images)
|
|
|
|
RegisterUC->>UserRepo: get_user_by_name(username)
|
|
UserRepo->>MongoDB: Query user by name
|
|
MongoDB-->>UserRepo: User data or null
|
|
UserRepo-->>RegisterUC: User entity or null
|
|
|
|
alt User doesn't exist
|
|
RegisterUC->>UserRepo: save(new_user)
|
|
UserRepo->>MongoDB: Insert new user
|
|
MongoDB-->>UserRepo: User ID
|
|
UserRepo-->>RegisterUC: User ID
|
|
end
|
|
|
|
loop For each image
|
|
RegisterUC->>S3: put_object(image)
|
|
S3-->>RegisterUC: s3_uri
|
|
|
|
RegisterUC->>TaskPub: publish_register_task(user_id, s3_uri)
|
|
TaskPub->>MQ: enqueue(task)
|
|
end
|
|
|
|
RegisterUC->>StatusRepo: wait/poll for task_ids status
|
|
StatusRepo-->>RegisterUC: Completed/Failed + results
|
|
|
|
alt All tasks completed
|
|
RegisterUC->>StatusRepo: get_mean_embedding(user_id) / or compute later
|
|
RegisterUC-->>GradioUI: Success message + stats
|
|
else Some tasks failed
|
|
RegisterUC-->>GradioUI: Partial success + failed items
|
|
end
|
|
GradioUI-->>User: Registration result (async aware)
|
|
|
|
%% Worker side
|
|
loop Worker Pool
|
|
MQ-->>Worker: task(user_id, s3_uri)
|
|
Worker->>S3: get_object(s3_uri)
|
|
Worker->>Detector: detect_faces(image)
|
|
Detector-->>Worker: faces
|
|
|
|
alt No faces or low quality
|
|
Worker->>StatusRepo: update(task_id, failed_reason)
|
|
else Face OK
|
|
Worker->>Detector: align_face(image, landmarks)
|
|
Detector-->>Worker: aligned_face
|
|
|
|
Worker->>Recognizer: extract_embedding(aligned_face)
|
|
Recognizer-->>Worker: embedding
|
|
|
|
Worker->>FaceRepo: save(face_entity)
|
|
FaceRepo->>MongoDB: insert face record
|
|
MongoDB-->>FaceRepo: ok
|
|
|
|
Worker->>VectorStore: add(face_id, embedding, metadata)
|
|
VectorStore->>ChromaDB: store vector
|
|
ChromaDB-->>VectorStore: ok
|
|
|
|
Worker->>StatusRepo: update(task_id, success, embedding_id)
|
|
end
|
|
end
|
|
```
|
|
|
|
## 2. Face Verification Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant VerifyUC as VerifyFaceUseCase
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant S3 as S3ObjectStorage
|
|
participant TaskPub as TaskPublisher
|
|
participant MQ as RabbitMQ
|
|
participant StatusRepo as TaskStatusRepository
|
|
participant Worker as FaceWorker
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant FaceRepo as MongoDBFaceRepository
|
|
participant MongoDB as MongoDB Database
|
|
|
|
User->>GradioUI: Upload image + username
|
|
GradioUI->>VerifyUC: execute(username, image)
|
|
|
|
VerifyUC->>UserRepo: get_user_by_name(username)
|
|
UserRepo->>MongoDB: Query user by name
|
|
MongoDB-->>UserRepo: User data or null
|
|
UserRepo-->>VerifyUC: User entity or null
|
|
|
|
alt User not found
|
|
VerifyUC-->>GradioUI: VerificationResult(false, 0.0)
|
|
GradioUI-->>User: result
|
|
else User found
|
|
VerifyUC->>S3: put_object(image)
|
|
S3-->>VerifyUC: s3_uri
|
|
|
|
VerifyUC->>TaskPub: publish_verify_task(user_id, s3_uri)
|
|
TaskPub->>MQ: enqueue(task)
|
|
VerifyUC->>StatusRepo: wait/poll task_id
|
|
StatusRepo-->>VerifyUC: (is_verified, score)
|
|
|
|
VerifyUC-->>GradioUI: VerificationResult
|
|
GradioUI-->>User: result
|
|
end
|
|
|
|
%% Worker side
|
|
MQ-->>Worker: task(user_id, s3_uri)
|
|
Worker->>S3: get_object(s3_uri)
|
|
Worker->>Detector: detect_faces(image)
|
|
Detector-->>Worker: faces
|
|
|
|
alt No faces
|
|
Worker->>StatusRepo: update(task_id, false, 0.0)
|
|
else
|
|
Worker->>Detector: align_face(image, landmarks)
|
|
Detector-->>Worker: aligned
|
|
|
|
Worker->>Recognizer: extract_embedding(aligned)
|
|
Recognizer-->>Worker: query_embedding
|
|
|
|
Worker->>FaceRepo: get_by_user_id(user_id)
|
|
FaceRepo->>MongoDB: query faces
|
|
MongoDB-->>FaceRepo: records
|
|
FaceRepo-->>Worker: embeddings
|
|
|
|
Worker->>Recognizer: calculate_similarity(query_embedding, user_embeddings)
|
|
Recognizer-->>Worker: max_score
|
|
|
|
Worker->>StatusRepo: update(task_id, max_score>=threshold, max_score)
|
|
end
|
|
```
|
|
|
|
## 3. Face Identification Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant GradioUI as Gradio Interface
|
|
participant IdentifyUC as IdentifyFaceUseCase
|
|
participant S3 as S3ObjectStorage
|
|
participant TaskPub as TaskPublisher
|
|
participant MQ as RabbitMQ
|
|
participant StatusRepo as TaskStatusRepository
|
|
participant Worker as FaceWorker
|
|
participant Detector as RetinaFaceDetector
|
|
participant Recognizer as SFaceRecognizer
|
|
participant VectorStore as ChromaDBVectorStore
|
|
participant ChromaDB as ChromaDB Vector DB
|
|
participant UserRepo as MongoDBUserRepository
|
|
participant MongoDB as MongoDB Database
|
|
|
|
User->>GradioUI: Upload image
|
|
GradioUI->>IdentifyUC: execute(image)
|
|
|
|
IdentifyUC->>S3: put_object(image)
|
|
S3-->>IdentifyUC: s3_uri
|
|
|
|
IdentifyUC->>TaskPub: publish_identify_task(s3_uri, top_k=10)
|
|
TaskPub->>MQ: enqueue(task)
|
|
|
|
IdentifyUC->>StatusRepo: wait/poll task_id
|
|
StatusRepo-->>IdentifyUC: (best_user_id, confidence, candidate_user_ids)
|
|
|
|
loop For each candidate_user_id
|
|
IdentifyUC->>UserRepo: get_by_id(user_id)
|
|
UserRepo->>MongoDB: query
|
|
MongoDB-->>UserRepo: user data
|
|
UserRepo-->>IdentifyUC: User entity
|
|
end
|
|
|
|
IdentifyUC-->>GradioUI: IdentificationResult
|
|
GradioUI-->>User: result
|
|
|
|
%% Worker
|
|
MQ-->>Worker: task(s3_uri)
|
|
Worker->>S3: get_object(s3_uri)
|
|
Worker->>Detector: detect_faces(image)
|
|
Detector-->>Worker: faces
|
|
|
|
alt No faces
|
|
Worker->>StatusRepo: update(task_id, null, 0.0, [])
|
|
else
|
|
Worker->>Detector: align_face(image, landmarks)
|
|
Detector-->>Worker: aligned
|
|
Worker->>Recognizer: extract_embedding(aligned)
|
|
Recognizer-->>Worker: query_embedding
|
|
|
|
Worker->>VectorStore: search_similar(query_embedding, top_k=10)
|
|
VectorStore->>ChromaDB: search
|
|
ChromaDB-->>VectorStore: results with metadata (face_id, user_id, score)
|
|
VectorStore-->>Worker: candidates
|
|
|
|
alt No scores above threshold
|
|
Worker->>StatusRepo: update(task_id, null, 0.0, [])
|
|
else
|
|
note over Worker: Group by user_id, choose best_user_id + confidence
|
|
Worker->>StatusRepo: update(task_id, best_user_id, confidence, candidate_user_ids)
|
|
end
|
|
end
|
|
```
|
|
|
|
## 4. System Initialization Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Main as main.py (API)
|
|
participant Config as Settings
|
|
participant MongoDBRepo as MongoDBFaceRepository
|
|
participant MongoUserRepo as MongoDBUserRepository
|
|
participant ChromaDB as ChromaDBVectorStore
|
|
participant S3 as S3ObjectStorage
|
|
participant Rabbit as RabbitMQ
|
|
participant StatusRepo as TaskStatusRepository
|
|
participant Publisher as TaskPublisher
|
|
participant GradioApp as Gradio Interface
|
|
|
|
participant WorkerMain as worker_main.py (Workers)
|
|
participant WConfig as Settings
|
|
participant WDetector as RetinaFaceDetector
|
|
participant WRecognizer as SFaceRecognizer
|
|
participant WFaceService as FaceRecognitionService
|
|
participant WFaceRepo as MongoDBFaceRepository
|
|
participant WVector as ChromaDBVectorStore
|
|
participant WS3 as S3ObjectStorage
|
|
participant WRabbit as RabbitMQ
|
|
participant WStatusRepo as TaskStatusRepository
|
|
participant WPool as FaceWorkerPool
|
|
|
|
%% API init
|
|
Main->>Config: Load configuration
|
|
Config-->>Main: Settings object
|
|
|
|
Main->>MongoDBRepo: Initialize with Mongo URL
|
|
Main->>MongoUserRepo: Initialize with Mongo URL
|
|
Main->>ChromaDB: Initialize with host/port
|
|
Main->>S3: Initialize with bucket/creds
|
|
Main->>Rabbit: Connect/create queues
|
|
Main->>StatusRepo: Initialize (Redis/Mongo)
|
|
Main->>Publisher: Initialize with Rabbit
|
|
Main->>GradioApp: create_gradio_interface(use_cases, publisher, status_repo)
|
|
Main->>GradioApp: launch(server_name, port)
|
|
|
|
%% Worker init (can be on separate machines)
|
|
WorkerMain->>WConfig: Load configuration
|
|
WConfig-->>WorkerMain: Settings
|
|
|
|
WorkerMain->>WRabbit: Connect/subscribe queues
|
|
WorkerMain->>WStatusRepo: Initialize
|
|
WorkerMain->>WDetector: Initialize RetinaFace
|
|
note over WDetector: Load ONNX models, prepare ctx
|
|
WorkerMain->>WRecognizer: Initialize SFace
|
|
note over WRecognizer: Load/Download ONNX model
|
|
WorkerMain->>WFaceRepo: Initialize with Mongo URL
|
|
WorkerMain->>WVector: Initialize with Chroma host/port
|
|
WorkerMain->>WS3: Initialize with bucket/creds
|
|
WorkerMain->>WFaceService: Initialize with dependencies
|
|
WorkerMain->>WPool: Start consuming tasks
|
|
```
|
|
|
|
## Flow Descriptions
|
|
|
|
### Registration Flow
|
|
1. User uploads multiple images with username
|
|
2. System checks if user exists, creates if needed
|
|
3. For each image: detects faces, validates quality, extracts embeddings
|
|
4. Stores face metadata in MongoDB, embeddings in ChromaDB, images in filesystem
|
|
5. Updates user with mean embedding for faster verification
|
|
|
|
### Verification Flow (1:1)
|
|
1. User provides image and username to verify against
|
|
2. System detects face in query image and extracts embedding
|
|
3. Retrieves all registered faces for the specified user
|
|
4. Compares query embedding with user's registered face embeddings
|
|
5. Returns verification result based on similarity threshold
|
|
|
|
### Identification Flow (1:N)
|
|
1. User provides image without specifying identity
|
|
2. System detects face and extracts embedding
|
|
3. Performs vector similarity search across all registered faces
|
|
4. Groups results by user and calculates confidence scores
|
|
5. Returns best match if confidence exceeds threshold
|
|
|
|
### Initialization Flow
|
|
System startup involves initializing all dependencies in correct order, loading ML models, and starting the web interface. |