ihtesham0345 commited on
Commit
d68c4e0
Β·
1 Parent(s): 3d17470

Update docs with A-Z guide for Qwen Model

Browse files
Files changed (1) hide show
  1. PROJECT_DOCS.md +37 -35
PROJECT_DOCS.md CHANGED
@@ -7,10 +7,10 @@ This project is an **AI-Powered Microservice** built with **FastAPI**. It serves
7
  - Competition Analysis
8
  - Strategic Tips
9
 
10
- **Key Feature:** Unlike traditional wrapper APIs, this project uses a **Local LLM (TinyLlama-1.1B)** embedded directly within the application. It does **not** rely on external paid APIs (like OpenAI or Gemini), ensuring it is:
11
- - **Free to run** (no per-token cost).
12
- - **Private** (data doesn't leave the container).
13
- - **Self-contained**.
14
 
15
  ---
16
 
@@ -32,8 +32,8 @@ Here is how the project files are organized:
32
 
33
  ```
34
  SEO_Analyzer_FastAPI/
35
- β”œβ”€β”€ main.py # οΏ½ Entry Point: Defines the API routes & server.
36
- β”œβ”€β”€ requirements.txt # πŸ“¦ Dependencies: Lists libraries (torch, fastapi, etc.).
37
  β”œβ”€β”€ Dockerfile # 🐳 Deployment: Instructions to build the Linux container.
38
  β”œβ”€β”€ models/
39
  β”‚ └── schemas.py # πŸ“ Data Models: Pydantic classes to validate input/output.
@@ -48,30 +48,27 @@ SEO_Analyzer_FastAPI/
48
  ### Step 1: Defining the Data Structure (`models/schemas.py`)
49
  Before writing code, we defined what the "Input" and "Output" should look like using **Pydantic**.
50
  - **Input**: A simple JSON object `{"content": "..."}`.
51
- - **Output**: A strict JSON schema ensuring the UI always receives `core_keywords`, `hashtags`, etc.
52
 
53
  ### Step 2: Building the Logic Core (`services/analyzer.py`)
54
- This is the most complex part. Instead of calling an external API, we:
55
- 1. **Initialize the Model**: On startup, we download `TinyLlama/TinyLlama-1.1B-Chat-v1.0` using `AutoModelForCausalLM`.
56
- 2. **Pipeline Creation**: We set up a Hugging Face `pipeline("text-generation")` to handle the complexity of tokenization and prediction.
57
- 3. **Prompt Engineering**: We crafted a specific "System Prompt" that forces the AI to act as an SEO expert and output **strict JSON**.
58
- > *"You are a professional SEO Data Scientist. You ONLY speak in valid JSON..."*
59
- 4. **Parsing**: The model outputs raw text. We wrote a helper function `clean_json_string` to strip away markdown code blocks and extract the pure JSON data for the API response.
 
60
 
61
  ### Step 3: Creating the API Endpoints (`main.py`)
62
  We created a FastAPI app with two routes:
63
- - `GET /`: A health check to confirm the server is running.
64
- - `POST /analyze-seo`: The main worker. It:
65
- 1. Receives the user's text.
66
- 2. Validates it against our Schema.
67
- 3. Passes it to the `analyzer.py` brain.
68
- 4. Returns the structured results.
69
 
70
  ### Step 4: Dockerization (`Dockerfile`)
71
- To make this run anywhere (local PC, Cloud, Hugging Face), we packaged it in a Docker container.
72
  - **Base Image**: `python:3.9`
73
- - **User Permissions**: Sets up a non-root user (id 1000) for security (required by HF Spaces).
74
- - **Commands**: Installs `requirements.txt` and starts the `uvicorn` server on port **7860**.
75
 
76
  ---
77
 
@@ -79,12 +76,13 @@ To make this run anywhere (local PC, Cloud, Hugging Face), we packaged it in a D
79
 
80
  1. **User Action**: Sends a request: `POST {"content": "dropshipping"}`.
81
  2. **API Layer**: FastAPI validates the request.
82
- 3. **Buisness Logic**:
83
- - The `analyzer` constructs a prompt.
84
- - The **TinyLlama** model runs the prompt through its neural network (locally on CPU).
85
- - The model generates a comprehensive analysis in text format.
86
- 4. **Processing**: Python extracts the JSON from the text.
87
- 5. **Response**: The user receives a clean JSON response with keywords, hashtags, and tips.
 
88
 
89
  ---
90
 
@@ -94,22 +92,26 @@ To make this run anywhere (local PC, Cloud, Hugging Face), we packaged it in a D
94
  ```bash
95
  pip install -r requirements.txt
96
  ```
97
- *(Note: This installs PyTorch, which is large ~2GB)*
98
 
99
- 2. **Run the Server**:
 
 
 
 
 
 
100
  ```bash
101
  python -m uvicorn main:app --reload
102
  ```
103
 
104
- 3. **Access Documentation**:
105
- Open your browser to `http://localhost:8000/docs` to see the interactive Swagger UI.
106
 
107
  ---
108
 
109
  ## 7. Configuration Limitations
110
- - **Hardware**: Running a 1.1 Billion parameter model requires about **3GB of RAM**.
111
- - **Speed**: On a standard CPU, generation might take 10-30 seconds. On a GPU, it takes <2 seconds.
112
- - **Max Length**: The model is configured to generate up to 1024 new tokens.
113
 
114
  ---
115
  **Developed by Ihtesham | Powered by Open Source AI**
 
7
  - Competition Analysis
8
  - Strategic Tips
9
 
10
+ **Key Feature:** This project leverages the **Qwen2.5-7B-Instruct** model, a state-of-the-art open-source LLM. Instead of running a heavy model locally, it connects to **Hugging Face's Serverless Inference API** to provide:
11
+ - **High Intelligence**: Comparable to GPT-3.5/4 for reasoning.
12
+ - **Speed**: Massive GPU acceleration without needing a local GPU.
13
+ - **Reliability**: Always-on availability.
14
 
15
  ---
16
 
 
32
 
33
  ```
34
  SEO_Analyzer_FastAPI/
35
+ β”œβ”€β”€ main.py # 🚦 Entry Point: Defines the API routes & server.
36
+ β”œβ”€β”€ requirements.txt # πŸ“¦ Dependencies: Lists libraries (huggingface_hub, fastapi, etc.).
37
  β”œβ”€β”€ Dockerfile # 🐳 Deployment: Instructions to build the Linux container.
38
  β”œβ”€β”€ models/
39
  β”‚ └── schemas.py # πŸ“ Data Models: Pydantic classes to validate input/output.
 
48
  ### Step 1: Defining the Data Structure (`models/schemas.py`)
49
  Before writing code, we defined what the "Input" and "Output" should look like using **Pydantic**.
50
  - **Input**: A simple JSON object `{"content": "..."}`.
51
+ - **Output**: A strict JSON schema ensuring the UI always receives `core_keywords`, `hashtags`, `relevance` scores, etc.
52
 
53
  ### Step 2: Building the Logic Core (`services/analyzer.py`)
54
+ This is the most complex part. We use the **Hugging Face Inference Client**:
55
+ 1. **Connection**: We initialize `InferenceClient(model="Qwen/Qwen2.5-7B-Instruct")`. This connects roughly to a cluster of A100 GPUs.
56
+ 2. **Prompt Engineering (The "Big Brain")**: We don't just ask "give me keywords". We send a **System Prompt** that instructs the AI:
57
+ > *"You are a World-Class SEO Strategist & Data Scientist... Analyze User Intent... Estimate metrics..."*
58
+ This ensures the output is professional-grade, not generic.
59
+ 3. **Chat Completion**: We use the `chat_completion` API format (`messages=[{"role": "system"...}, {"role": "user"...}]`) which Qwen understands perfectly.
60
+ 4. **Parsing**: The model outputs a JSON string. We parse this into a Python dictionary.
61
 
62
  ### Step 3: Creating the API Endpoints (`main.py`)
63
  We created a FastAPI app with two routes:
64
+ - `GET /`: A health check.
65
+ - `POST /analyze-seo`: The main worker. It has robust error handling (`try/except`) to catch any API issues and report them clearly.
 
 
 
 
66
 
67
  ### Step 4: Dockerization (`Dockerfile`)
68
+ To make this run on the cloud:
69
  - **Base Image**: `python:3.9`
70
+ - **Optimization**: We removed heavy libraries like `torch` and `transformers`. The container is now very small and fast because the AI runs remotely.
71
+ - **Port**: Exposes port **7860** for Hugging Face Spaces.
72
 
73
  ---
74
 
 
76
 
77
  1. **User Action**: Sends a request: `POST {"content": "dropshipping"}`.
78
  2. **API Layer**: FastAPI validates the request.
79
+ 3. **Business Logic**:
80
+ - The `analyzer` constructs the detailed "Strategic Prompt".
81
+ - It sends this prompt securely to Hugging Face's API.
82
+ - **Qwen-7B** (running on powerful cloud GPUs) analyzes the text.
83
+ - It returns a structured JSON response.
84
+ 4. **Processing**: Python validates the fields.
85
+ 5. **Response**: The user receives the data with keyword volumes, competition, and strategy.
86
 
87
  ---
88
 
 
92
  ```bash
93
  pip install -r requirements.txt
94
  ```
 
95
 
96
+ 2. **Set Environment Variables**:
97
+ Create a `.env` file and add your token:
98
+ ```
99
+ HF_TOKEN=hf_...
100
+ ```
101
+
102
+ 3. **Run the Server**:
103
  ```bash
104
  python -m uvicorn main:app --reload
105
  ```
106
 
107
+ 4. **Access Documentation**:
108
+ Open `http://localhost:8000/docs`.
109
 
110
  ---
111
 
112
  ## 7. Configuration Limitations
113
+ - **Rate Limits**: The free Serverless API has rate limits. If you spam it, you might get a 429 error. Adding your `HF_TOKEN` increases these limits.
114
+ - **Model Choice**: We selected `Qwen2.5-7B-Instruct` because it is currently the best performing 7B model available on the free tier.
 
115
 
116
  ---
117
  **Developed by Ihtesham | Powered by Open Source AI**