Skip to main content

​
System requirements

  • Python: 3.11 or higher
  • Docker: 20.10 or higher (for PostgreSQL with pgvector)
  • Docker Compose: 2.0 or higher
  • Memory: At least 4GB RAM recommended
  • Storage: 2GB free space for Docker images and database

​
Installation methods

​
Clone the repository

git clone https://github.com/your-username/sku-semantic-search.git
cd sku-semantic-search

​
Create a virtual environment

python -m venv venv
source venv/bin/activate

​
Install dependencies

pip install --upgrade pip
pip install -r requirements.txt
The project uses these major dependencies:
fastapi==0.134.0
uvicorn==0.41.0
sqlalchemy==2.0.47
psycopg2-binary==2.9.11
pgvector==0.4.2
google-generativeai==0.8.6
anthropic==0.84.0
python-jose==3.5.0
passlib==1.7.4
pydantic==2.12.5
pydantic-settings==2.13.1
See requirements.txt for the complete list.

​
Set up PostgreSQL with pgvector

Start the database using Docker Compose:
docker-compose up -d db
Verify the database is running:
docker ps
You should see a container named retail_rag_db with status “Up” and “(healthy)”.

​
Configure environment variables

Create a .env file in the project root:
cp .env.example .env  # if you have an example file
# or create it manually
Add the following configuration:
PROJECT_NAME="SKU Semantic Search"
VERSION="1.0.0"

# Database configuration
DATABASE_URL="postgresql://postgres:db_pass@localhost:5435/retail_rag"

# AI provider API keys
GEMINI_API_KEY="your_gemini_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here"

# JWT authentication
JWT_SECRET="your_very_secure_random_secret_key"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
Never commit your .env file to version control. Add it to .gitignore to prevent accidentally exposing your API keys.

​
Initialize the database

The database schema is automatically created when you first run the application:
uvicorn app.main:app --reload
The startup code in app/main.py:8 creates the pgvector extension and all necessary tables:
def create_tables():
    with engine.connect() as conn:
        conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
        conn.commit()
    Base.metadata.create_all(bind=engine)

​
Seed sample data

Populate the database with sample products:
python seed_data.py
This script creates embeddings for each product and stores them in PostgreSQL.
The seed script includes a 0.5-second delay between products to avoid hitting Google Gemini API rate limits.

​
Verify installation

Test that everything is working:
1

Check API health

curl http://localhost:8000/
Expected response:
{
  "message": "API de Búsqueda Semántica de SKUs lista y Base de Datos conectada"
}
2

Get authentication token

curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"
3

Test semantic search

Replace YOUR_TOKEN with the token from step 2:
curl -X POST "http://localhost:8000/products/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "bebida refrescante", "limit": 3}'
You should receive product recommendations with an AI-generated response.

​
Troubleshooting

If you see connection refused errors:
  1. Ensure PostgreSQL is running: docker ps
  2. Check the port isn’t already in use: lsof -i :5435 (macOS/Linux)
  3. Verify the DATABASE_URL in your .env file matches the Docker Compose configuration
The Docker Compose file exposes PostgreSQL on port 5435 (not the default 5432) to avoid conflicts:
ports:
  - "5435:5432"
If you see embedding or generation errors:
  1. Verify your API key is correct in .env
  2. Check you haven’t exceeded the free tier quota
  3. Ensure your IP isn’t blocked (try from a different network)
The system will automatically fall back to Claude if Gemini fails for generation, but embeddings always use Gemini.
If Python can’t find the app module:
  1. Ensure you’re in the project root directory
  2. Verify your virtual environment is activated
  3. Try reinstalling: pip install -r requirements.txt --force-reinstall
If the Docker image won’t build:
  1. Ensure you have enough disk space: docker system df
  2. Clean up old images: docker system prune -a
  3. Check the Dockerfile for syntax errors

​
Next steps

Quickstart

Follow the quickstart guide to make your first API call

Environment setup

Learn about all configuration options

Database setup

Deep dive into PostgreSQL and pgvector configuration

Architecture

Understand how the system works

Build docs developers (and LLMs) love

Get started for freeTalk to us