DEV Community: yukaty

A Portfolio That Actually Gets Read

yukaty — Thu, 29 Jan 2026 20:33:23 +0000

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

I'm a software developer and technical educator with over a decade of experience. As a Deaf, non-native English speaker, I've learned that the real challenge isn't mastering complex topics, but explaining them so anyone can understand.

My experience felt broad and hard to present clearly. Rather than listing everything, I built a portfolio to simply showcase my work and my commitment to accessibility and clarity.

Portfolio

Source code available on GitHub.

How I Built It

The Problem

A technical recruiter once told me about my old portfolio: "I am not technical, so your website sadly means nothing to me."

That feedback stuck with me. Even technical recruiters often don't have coding backgrounds. I wanted to build one that works for everyone, not only for developers.

The Solution: An AI Assistant with Two Voices

I built a portfolio chatbot powered by RAG (Retrieval-Augmented Generation) that can answer questions about my skills and experience. Its key feature is simpler than RAG itself.

The chatbot speaks two languages. Professional and Plain, not English and French.

Professional Mode: Technical terminology, concise phrasing, domain expertise
Plain Mode: Same information, accessible language, focus on "what" over "how"

Tech Stack

Frontend: React 19, TypeScript, Tailwind CSS
Backend: FastAPI, Python, FAISS
Infrastructure: Google Cloud Run, GitHub Actions, Docker
AI: Gemini API (gemini-2.5-flash for chat, gemini-embedding-001 for embeddings)

I used Antigravity for rapid UI testing, validating different user journeys for HR, Engineering Managers, and accessibility-first users. AI Studio helped me adjust system prompts, testing until the chatbot responses felt right. Gemini CLI supported implementation and refactoring. Although the Google AI tools sped up my workflow, I still spent most of my time refining prompts, checking outputs, and adjusting decisions step by step.

Key Technical Decisions

This architecture mirrors real-world AI systems, but is intentionally minimal to fit the size of a portfolio.

RAG for Traceability

Long context would work fine for a few markdown files, but RAG provides traceability (which documents the AI used) and demonstrates a production-ready AI pattern. It could also help reduce token usage if I later integrate a blog or additional content.

Confidence Scoring for Quality Monitoring

Each response is evaluated based on retrieved context. When confidence is low, the AI guides users to contact me directly via LinkedIn. Metrics are logged for monitoring but never shown to users.

Security Considerations

The backend includes prompt injection detection and PII filtering. Conversations are never stored. Only anonymous metadata is logged for monitoring.

What I'm Most Proud Of

1. Accessibility as Foundation

Accessibility is often discussed as visual or motor support, but cognitive accessibility matters too.

Technical jargon creates barriers for non-technical stakeholders, non-native speakers, and anyone outside your specific domain. The Language Mode toggle is a small feature, but it shows that I care about bridging these gaps.

Beyond language, I adjusted contrast, ARIA usage, and interaction details across the UI to meet WCAG AA.

Clean design, readable code, clear documentation. These aren't extras.

2. Right-Sized Engineering

I wanted to demonstrate good judgment, knowing what to build and what to skip.

For a portfolio chatbot with a small knowledge base, I chose minimal RAG with in-memory FAISS. It loads quickly, costs nothing, and requires no database infrastructure.

I also added Quick Response buttons with pre-written answers. If the AI fails or responds slowly, users still get reliable answers instantly. It's not flashy, but it's the kind of thinking that matters in production.

This challenge was the perfect push to finally update a portfolio I'd been putting off for years. Thanks to DEV and Google AI team for the opportunity!

48 Hours to Learn AI Agents: How It Changed My View

yukaty — Sun, 14 Dec 2025 23:08:53 +0000

This is a submission for the Google AI Agents Writing Challenge: Learning Reflections

I found this writing challenge the day before the deadline.

To save time, I used NotebookLM for the first time and fed the course materials into it. I didn't grasp everything. Some ideas are still vague. Yet in just two days, my understanding of AI agents and the future role of engineers became clearer.

This post is a reflection on what I learned and what I'm still thinking about.

What Even Is an AI Agent?

Before this course, I couldn't clearly explain what an AI agent actually is. My mental image was vague, like a powerful model, some clever prompts, a bunch of files, and glue code holding it all together. The AI field has been moving so fast that I've felt overwhelmed trying to keep up with what's new versus what's actually different.

What clicked for me was seeing the agent framed as a system, not just a model. You need a model for reasoning, tools for acting, and orchestration logic for deciding when and how to use them. The model is the brain, but without hands (tools) and a plan (orchestration), it's just thinking out loud. And worse, it can sound confident even when it's wrong.

Context and Contracts

One concept that stayed with me was “mise en place”, the cooking principle of preparing ingredients before you start. Instead of endlessly tweaking prompts, the course emphasized asking different questions. What information do we give the agent? When do we give it? What do we intentionally leave out? The quality of an agent's output relies more on the context humans provide than on clever wording.

The Model Context Protocol (MCP) section reinforced this. Standardizing how agents interact with tools sounds dry at first, but tools are how agents act. Someone still has to define the contracts, schemas, and boundaries.

Just like we needed REST to make APIs interoperable, we need protocols like MCP to make agent-tool interactions predictable and safe. Execution can be automated. The rules governing it cannot. We're responsible for both the input and the outcome.

Trust, Quality, and the Role of Engineers

I have worked in roles where quality and trust matter, across software, documentation, and education. Seeing the same concerns emerge in agent systems made the topic feel personal rather than abstract.

The most memorable part of the discussion was about agent quality and AgentOps. Unlike traditional software testing, AI agents don’t produce the same output every time. The idea that "the trajectory is the truth" means we should evaluate not only the final answer but also the steps an agent took, the tools it chose, and how it handled errors. That shift has changed how I think about trusting AI.

It also made me reflect on my own role. Technology keeps changing, but the fundamentals stay the same, understanding architecture, ensuring quality, and maintaining stability. The real challenge now is learning how to work with AI effectively.

Final Thought

For a course I joined with 48 hours left, I came away with new questions, several project ideas, and a clearer sense of where human judgment still matters. That feels like a meaningful outcome, even if it also made the gaps in my understanding more obvious.

As AI agents get better at execution, engineers are becoming more responsible for deciding what gets executed and how, instead of handing those decisions over entirely to the AI. I don't think this role is smaller. If anything, it feels heavier and more interesting.

I'm excited to start building my own ideas with AI agents.

Tech Trend Tracker: AI-Powered News Analysis for Technology Insights

yukaty — Sat, 28 Dec 2024 18:40:11 +0000

This is a submission for the Bright Data Web Scraping Challenge: Build a Web Scraper API to Solve Business Problems

What I Built

Tech Trend Tracker tracks technology trends from Reuters news articles, helping businesses effectively monitor industry movements through keyword rankings and semantic article search.

Features:

Collect and process news articles using Bright Data's Web Scraper API
Track technology companies, industry leaders, and products with keyword rankings
Enable semantic article search using OpenAI embeddings and pgvector
Display interactive dashboards for keyword trends and entity rankings

Demo

⚡️ Live demo: Tech Trend Tracker

🐙 Source code: GitHub

Screenshots:

The dashboard shows keyword rankings of tech companies, people, and services. Click any entity to see all related articles (keyword matching).

Beyond basic keyword matching, the semantic search bar uses OpenAI embeddings to find conceptually similar articles.

How I Used Bright Data

The project leverages Bright Data's Web Scraper API to collect Reuters technology articles efficiently and reliably. I implemented:

Optimized batch collection with configurable time ranges
Robust error handling and retry logic
Structured data extraction for seamless processing

Additional Qualification:

This project might also qualify for "Prompt 3: Most Creative Use of Web Data for AI Models" as it leverages embeddings for semantic search and entity recognition.

This project brings together the tech stack I explored in 2024. I enjoyed working on the holiday project!

Mastering Docker Compose: A Practical Guide for Developers 🚀

yukaty — Tue, 17 Dec 2024 18:16:59 +0000

Looking to improve your development workflow with Docker Compose? This guide covers everything developers should know - from basic setup to common troubleshooting patterns.

Table of Contents 📋

What is Docker Compose?
Basic Setup
Development Workflow
Essential Commands
Troubleshooting
Advanced Features
Conclusion

What is Docker Compose? 🐙

Docker Compose makes it easy to run multiple containers together. This is a great tool for local development and testing without messing your machine.

Instead of starting each service (like the database, backend, and frontend) separately, Compose lets you define everything in a single file compose.yml (or docker-compose.yml for older versions) and start them with a single command.

Basic Setup 📌

Docker Compose Template

Here’s a minimal yet practical template for a backend app and database:

services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DB_HOST=database
      - DB_USER=postgres
      - DB_PASSWORD=secretpassword
    depends_on:
      # Waits for 'database' service to start
      - database
    volumes:
      # Mounts local directory to container for live code updates
      - ./backend:/app

  database:
    image: postgres:17
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=secretpassword
    volumes:
      # Persists data using named volume 'db_data'
      - db_data:/var/lib/postgresql/data

volumes:
  # Declares the named volume
  db_data:

Key Features:

depends_on: Ensures services start in order.
volumes: Supports persistent data and live code updates.
Environment variables: Simple configuration for connections.

Configuration Priority

Docker Compose uses this file priority:

1. compose.yml
2. compose.yaml
3. compose.override.yml
4. compose.override.yaml

Note: docker-compose.yml was the standard name for many years. While still valid, Docker now defaults to compose.yml in modern projects. If you are using an older environment or tools, docker-compose.yml will still work seamlessly.

You can use override files for development-specific settings:

# compose.yml (base configuration)
services:
  backend:
    build: ./backend
    environment:
      - NODE_ENV=production

# compose.override.yml (development overrides)
services:
  backend:
    environment:
      - NODE_ENV=development
    volumes:
      - ./backend:/app

Ignore overrides with:

docker compose -f compose.yml up -d

Development Workflow 🔄

Practical usage of Docker Compose during your daily development cycle.

1. Service Lifecycle

Basic commands to start and stop your development environment.

# Start services
docker compose up -d          # Detached mode (runs in background)
docker compose up --build     # Rebuild images and start services

# Stop services
docker compose stop           # Stops running containers without removing them
docker compose down           # Stops and removes containers and networks

2. Monitoring

Frequently used commands to check service status and debug issues.

# Check running services
docker compose ps

# View service logs for all services
docker compose logs -f

3. Iteration Cycles (Handling Changes)

Choose the right command based on what you have modified:

Code Changes: Restart the specific service to apply changes quickly.

docker compose restart backend

Dockerfile or Dependency Changes: Rebuild the image and restart the service.

docker compose up --build backend

Full Cleanup and Reset: Use this when you need a completely fresh state.

docker compose down -v            # Stop and clean up everything (including volumes)
docker compose up --build         # Rebuild and restart all services

Essential Commands 💡

Cleaning Up Services

Keeping your environment clean is essential. Here are the key commands for managing unused resources and containers:

Command	Description
`docker compose down -v`	Stops and removes all containers, networks, and volumes.
`docker compose down --remove-orphans`	Removes unused containers not defined in the `compose.yml`.
`docker system prune`	Removes all stopped containers, unused networks, dangling images, and build cache.
`docker volume prune`	Removes all unused volumes.
`docker system prune -a`	Additionally removes all unused images, not just dangling ones.

Usage:

down -v: Use for a complete cleanup, including persistent data and volumes.
down --remove-orphans: Ideal for clearing out leftover or unrelated containers.
system prune: Regular maintenance to free up space.
volume prune: Remove unused data volumes to reclaim space.
system prune -a: Deep cleanup when disk space is low.

Building and Starting Services

Here’s a quick reference for commonly used commands to build images and start containers:

Command	Description
`docker compose up`	Starts services defined in `compose.yml`.
`docker compose up --build`	Rebuilds service images and starts services together.

Usage:

up: Start containers when images are already built.
up --build: Rebuild and start services in one step.

Working with Containers

You can interact with containers using Service Names:

docker compose exec database bash                      # Access the container shell
docker compose exec database psql -U postgres -d myapp # Connect to the PostgreSQL

Note: Service names are defined in the services section of compose.yml.

Troubleshooting 🛠️

Port Allocation Errors

When you see an error like this:

Error: Bind for 0.0.0.0:8000 failed: port is already allocated

It means the local port 8000 is already in use.

Solutions:

1. Check Port Usage: Find the process using the port:

lsof -i :8000

2. Kill the Process: Terminate the process occupying the port:

kill -9 <PID>

3. Change the Port: Update compose.yml to use a different local port:

ports:
  - "8080:8000"  # Map local port 8080 to container port 8000

Storage and Resource Errors

When building or running containers, you might encounter this common error:

Error: failed to solve: failed to copy files: userspace copy failed: write /var/lib/docker/***: no space left on device

This indicates insufficient disk space.

Solutions:

1. Clean up Docker system:

docker system prune -a

2. Check available space:

df -h

3. Remove dangling images:

docker images -a | grep none | awk '{ print $3; }' | xargs docker rmi

4. Clean unused volumes:

docker volume prune

If issues persist, consider expanding your storage capacity.

Advanced Features ⚡

Network Configuration

Define custom networks to enable secure communication between services:

services:
  backend:
    networks:
      - app-network

  database:
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Tip: Use docker network ls and docker network inspect to troubleshoot network issues.

Health Checks

Ensure services are ready before other services depend on them:

services:
  database:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Purpose: Prevents dependent services from starting too early.

Resource Management

Control resource usage to ensure stable performance:

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

Purpose: Avoids a single service consuming too many resources.

Conclusion 🎯

Docker Compose might look complex at first, but understanding these basics will help you manage most situations.

Start simple.
Use the right command for the task.
Keep your environment clean.

I hope this guide is helpful. Let me know if you have suggestions or spot anything I missed! 💬

Happy containerizing! 🐳

Understanding React in 5 mins

yukaty — Mon, 25 Nov 2024 13:09:20 +0000

Looking for a quick way to grasp the basics of React? Feeling overwhelmed by lengthy tutorials? In just 5 minutes, you'll learn enough to read and understand most React code.

Table of Contents

What is React?
Core Concepts
Common Patterns
Putting It All Together
That's It!

What is React?

React is a JavaScript library for building UIs like buttons or forms.

Think of building with LEGO blocks. Instead of creating one big castle, you build using smaller, reusable pieces that connect together. React lets you build web interfaces using reusable pieces called "components".

Here's what React code looks like:

// A simple React component
function Greeting() {
  return <h1>Hello!</h1>;
}

This special syntax is called JSX - it lets you write HTML-like code in JavaScript.

React helps you:

Break down complex UIs into manageable pieces
Handle UI and data efficiently using a Virtual DOM system
Update webpages automatically whenever your data changes

Core Concepts

1. Components 🧩

Components are like LEGO blocks in React. They are reusable UI pieces you can combine.

// A simple component
function Welcome({ name }) {
  return <h1>Hello, {name}!</h1>;
}

// Using it
<Welcome name="Alice" />

2. Props 📨

Props are data passed to components - like function parameters.

// 'name' and 'age' are passed to UserCard() as props
function UserCard({ name, age }) {
  return (
    <div>
      <h2>{name}</h2>
      <p>Age: {age}</p>
    </div>
  );
}

<UserCard name="Alice" age={25} />

Note: Props are read-only.

3. State 📝

State is data that can change. When it changes, React updates the UI automatically.

function LikeButton() {
  // 'likes' is state
  // 'setLikes' is function to update the state
  const [likes, setLikes] = useState(0);

  return (
    <button onClick={() => setLikes(likes + 1)}>
      Likes: {likes}
    </button>
  );
}

Note: useState(0) sets up state with an initial value of 0 (more about Hooks below).

4. Hooks 🪝

Hooks are functions that let components use React features. They always start with "use".

useState: for managing changing data (state)

const [count, setCount] = useState(0); // Initialize count with 0

useEffect: for running code at specific times (like API calls)

useEffect(() => {
    fetchData(); // Get data
}, []);          // Run once when page loads

Common Patterns

Conditional Rendering

Show different content based on conditions:

function Greeting({ isLoggedIn }) {
  return isLoggedIn
   ? <h1>Welcome!</h1>
   : <h1>Please log in</h1>;
}

When isLoggedIn is true, shows "Welcome!", otherwise shows "Please log in".

Usage:

<Greeting isLoggedIn={true} />   // "Welcome!"
<Greeting isLoggedIn={false} />  // "Please log in"

Event Handling

Handle user interactions like clicks:

function ToggleButton() {
 // Track button state (ON/OFF)
  const [isOn, setIsOn] = useState(false);

  return (
    <button onClick={() => setIsOn(!isOn)}>
      {isOn ? 'ON' : 'OFF'}
    </button>
  );
}

When clicked, the button text switches between "ON" and "OFF".

Usage:

<ToggleButton />  // Shows: "OFF" by default

Putting It All Together 👀

Here's a real example using what we learned:

function LikeButton({ initialLikes = 0 }) {
  const [likes, setLikes] = useState(initialLikes);

  return (
    <button onClick={() => setLikes(likes + 1)}>
      {likes === 0 ? '♡' : '🩷'} {likes > 0 && likes}
    </button>
  );
}

This LikeButton component:

Gets initial likes count as props
Shows empty heart (♡) when count is 0
Shows pink heart (🩷) with number when likes > 0
Updates heart and count when clicked

Usage Example:

<LikeButton initialLikes={0} />  // ♡
<LikeButton initialLikes={8} />  // 🩷 8

That's It! 🥳

You now know the React basics! While there's more to learn, you can understand most React code you see.

Ready to Start?

There are several ways to create a React project:

Next.js: Full-stack React framework, recommended for most new projects
Gatsby: React framework for fast CMS-backed websites
Vite: Modern and fast build tool, great for learning React and building single-page applications

Details are here.

Happy coding✨

PWA Quick Guide: Make Your React App Installable

yukaty — Tue, 19 Nov 2024 15:41:04 +0000

Want to make your web app feel like a real mobile app? PWA (Progressive Web App) is the answer!

Prerequisites 📋

This guide is for React apps built with Vite. Some frameworks like Next.js and Gatsby have built-in PWA support, so choose what works best for your project.

What You'll Build 🧑‍💻

After following this guide, your React app will:

Be installable on any device
Work without internet
Look and feel like a native app

Browser support notes

Chrome/Edge/Firefox: Full PWA support
Safari: Limited PWA support

Let's get started!

Step 1. Create a new React project

npm create vite@latest my-pwa-app
cd my-pwa-app
npm install

**Skip this step if you already have your app.

Step 2. Install the PWA package

npm install vite-plugin-pwa -D

💡 This plugin manages internally:

Web App Manifest - defines how your app appears and behaves
Service Worker - makes your app work offline

Step 3. Configure PWA

Update vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { VitePWA } from 'vite-plugin-pwa'

const manifestIcons = [
  {
    src: 'pwa-192.png',
    sizes: '192x192',
    type: 'image/png',
  },
  {
    src: 'pwa-512.png',
    sizes: '512x512',
    type: 'image/png',
  }
]

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'My Awesome App',
        short_name: 'PWA App',
        icons: manifestIcons,
      }
    })
  ]
})

Step 4. Add app icons

Create two icons and place them in your public folder:

192x192 pixels (name it pwa-192.png)
512x512 pixels (name it pwa-512.png)

Need help creating icons? Try Favicon.io or PWA Asset Generator.

Step 5. Test Your PWA

# Development mode
npm run dev         # http://localhost:5173

# Production mode
npm run build
npm run preview     # http://localhost:4173

💡Production mode is recommended for testing full PWA features.

Testing Checklist

Check installation:

Open in Chrome
Look for install icon in address bar
Open Chrome DevTools (F12) → Application tab → Service Workers to verify registration

Test offline mode:

Install the app
In Chrome DevTools → Network tab, check "Offline"
App should still work!

Troubleshooting

No install icon? - Use production build
Changes not showing? - Clear browser cache
Double-check icon paths in the public folder

Next Steps 🐾

This is just the beginning - there's a lot more you can do with PWAs. Explore:

Push notifications
Offline data sync
Custom install prompts

Resources:

That's it! Now you know how to create a Progressive Web App (PWA) 🥳

Happy coding ❤️

Part 3: Implementing Vector Search with Ollama

yukaty — Tue, 12 Nov 2024 20:03:20 +0000

Part 1 covered PostgreSQL with pgvector setup, and Part 2 implemented vector search using OpenAI embeddings. This final part demonstrates how to run vector search locally using Ollama! ✨

Why Ollama?
Setting Up Ollama with Docker
Database Updates
Implementation
Search Queries
Performance Tips
Troubleshooting
OpenAI vs. Ollama
Wrap Up

Why Ollama? 🦙

Ollama allows you to run AI models locally with:

Offline operation for better data privacy
No API costs
Fast response times

We'll use the nomic-embed-text model in Ollama, which creates 768-dimensional vectors (compared to OpenAI's 1536 dimensions).

Setting Up Ollama with Docker 🐳

To add Ollama to your Docker setup, add this service to compose.yml:

services:
  db:
    # ... (existing db service)

  ollama:
    image: ollama/ollama
    container_name: ollama-service
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

  data_loader:
    # ... (existing data_loader service)
    environment:
      - OLLAMA_HOST=ollama
    depends_on:
      - db
      - ollama

volumes:
  pgdata:
  ollama_data:

Then, start the services and pull the model:

docker compose up -d

# Pull the embedding model
docker compose exec ollama ollama pull nomic-embed-text

# Test embedding generation
curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "Hello World"
}'

Database Updates 🐘

Update the database to store Ollama embeddings:

-- Connect to the database
docker compose exec db psql -U postgres -d example_db

-- Add a column for Ollama embeddings
ALTER TABLE items
ADD COLUMN embedding_ollama vector(768);

For fresh installations, update postgres/schema.sql:

CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    item_data JSONB,
    embedding vector(1536),        # OpenAI
    embedding_ollama vector(768)   # Ollama
);

Implementation 👾

Update requirements.txt to install the Ollama Python library:

ollama==0.3.3

Here’s an example update for load_data.py to add Ollama embeddings:

import ollama  # New import

def get_embedding_ollama(text: str):
    """Generate embedding using Ollama API"""
    response = ollama.embed(
        model='nomic-embed-text',
        input=text
    )
    return response["embeddings"][0]

def load_books_to_db():
    """Load books with embeddings into PostgreSQL"""
    books = fetch_books()

    for book in books:
        description = (
            f"Book titled '{book['title']}' by {', '.join(book['authors'])}. "
            f"Published in {book['first_publish_year']}. "
            f"This is a book about {book['subject']}."
        )

        # Generate embeddings with both OpenAI and Ollama
        embedding = get_embedding(description)                # OpenAI
        embedding_ollama = get_embedding_ollama(description)  # Ollama

        # Store in the database
        store_book(book["title"], json.dumps(book), embedding, embedding_ollama)

Note that this is a simplified version for clarity. Full source code is here.

As you can see, the Ollama API structure is similar to OpenAI’s!

Search Queries 🔍

Search query to retrieve similar items using Ollama embeddings:

-- View first 5 dimensions of an embedding
SELECT
    name,
    (replace(replace(embedding_ollama::text, '[', '{'), ']', '}')::float[])[1:5] as first_dimensions
FROM items;

-- Search for books about web development:
WITH web_book AS (
    SELECT embedding_ollama FROM items WHERE name LIKE '%Web%' LIMIT 1
)
SELECT
    item_data->>'title' as title,
    item_data->>'authors' as authors,
    embedding_ollama <=> (SELECT embedding_ollama FROM web_book) as similarity
FROM items
ORDER BY similarity
LIMIT 3;

Performance Tips 📊

Add an Index

CREATE INDEX ON items
USING ivfflat (embedding_ollama vector_cosine_ops)
WITH (lists = 100);

Resource Requirements

RAM: ~2GB for the model
First query: Expect slight delay for model loading
Subsequent queries: ~50ms response time

GPU Support

If processing large datasets, GPU support can greatly speed up embedding generation. For details, refer to the Ollama Docker image.

Troubleshooting 🔧

Connection Refused Error

The Ollama library needs to know where to find the Ollama service. Set the OLLAMA_HOST environment variable in data_loader service:

data_loader:
  environment:
    - OLLAMA_HOST=ollama

Model Not Found Error

Pull the model manually:

docker compose exec ollama ollama pull nomic-embed-text

Alternatively, you can add a script to automatically pull the model within your Python code using the ollama.pull() function.

High Memory Usage

Restart Ollama service
Consider using a smaller model

OpenAI vs. Ollama ⚖️

Feature	OpenAI	Ollama
Vector Dimensions	1536	768
Privacy	Requires API calls	Fully local
Cost	Pay per API call	Free
Speed	Network dependent	~50ms/query
Setup	API key needed	Docker only

Wrap Up 🌯

This tutorial covered only how to set up a local vector search with Ollama. Real-world applications often include additional features like:

Query optimization and preprocessing
Hybrid search (combining with full-text search)
Integration with web interfaces
Security and performance considerations

The full source code, including a simple API built with FastAPI, is available on GitHub. PRs and feedback are welcome!

Resources:

Questions or feedback? Leave a comment below! 💬

Part 2: Implementing Vector Search with OpenAI

yukaty — Thu, 07 Nov 2024 02:12:59 +0000

In Part 1, we set up PostgreSQL with pgvector. Now, let's see how vector search actually works. 🧠

Prerequisites
Understanding Vector Search
Project Setup
Exploring Vector Search
Working with JSON and Vectors
Performance Tips
Resources

Prerequisites 📋

Completed Part 1 setup for pgvector
OpenAI API key

Understanding Vector Search 🌐

A vector is a list of numbers that represents position or direction:

2D Vector: [x, y]     📍 Like coordinates on a map
3D Vector: [x, y, z]  🎲 Like a point in 3D space

When AI processes content, it creates special vectors called "embeddings" (1536 dimensions) to represent meaning. These embeddings are stored in the database, allowing us to perform similarity search:

📘 "How to use Docker"
    [0.23, 0.45, 0.12, ...]  # 1536-dimensional vector
📗 "Docker tutorial"          
    [0.24, 0.44, 0.11, ...]  🤝 Very Similar! (Distance: 0.2)
📕 "Chocolate cake recipe"    
    [0.89, 0.12, 0.67, ...]  🚫 Not Related! (Distance: 0.9)

Vectors let AI understand similarity mathematically
Vector search finds similar content by comparing distances
pgvector stores embeddings efficiently
Works across any language (it's all just numbers!)

Project Setup ⚙️

Updated Project Structure

vector-search/
├── .env
├── compose.yml
├── requirements.txt
├── postgres/            # Part 1: Database setup
│   └── schema.sql
└── scripts/             # New: Data loading
    ├── Dockerfile
    └── load_data.py

1. Set Up OpenAI API

Create .env:

OPENAI_API_KEY=your_api_key  # Get from platform.openai.com

2. Create Data Loading Script

Create scripts/load_data.py to fetch books and generate embeddings:

import openai

client = openai.OpenAI()

def get_embedding(text: str):
    """Generate embedding using OpenAI API"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

def load_books_to_db():
    """Load books with embeddings into PostgreSQL"""

    # 1. Fetches books from Open Library API
    books = fetch_books()

    for book in books:
        # 2.Create text description for embedding
        description = f"Book titled '{book['title']}' by {', '.join(book['authors'])}. "
        description += f"Published in {book['first_publish_year']}. "
        description += f"This is a book about {book['subject']}."

        # 3. Generate embedding using OpenAI
        embedding = get_embedding(description)

        # 4. Stores books and embeddings in PostgreSQL
        store_book(book["title"], json.dumps(book), embedding)

Full source code is available on GitHub 🐙

Also create requirements.txt and scripts/Dockerfile.

3. Update Docker Compose

Update compose.yml to add the data loader:

services:
  # ... existing db service from Part 1

  data_loader:
    build:
      context: .
      dockerfile: scripts/Dockerfile
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/example_db
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - db
    command: python load_data.py

4. Load Sample Data

docker compose up --build

Exploring Vector Search 🔦

First, connect to the database:

docker exec -it pgvector-db psql -U postgres -d example_db

Inspecting Embeddings

Check what the vectors look like:

-- View first 5 dimensions of an embedding
SELECT
    name,
    (replace(replace(embedding::text, '[', '{'), ']', '}')::float[])[1:5] as first_dimensions
FROM items
LIMIT 1;

💡 Each embedding from OpenAI's model:

Has 1536 dimensions
Contains values between -1 and 1
Represents text meaning mathematically
Outputs in [...] format, which needs to be converted to PostgreSQL's {...} array format for array operations

Finding Similar Books

Search for books about web development:

WITH web_book AS (
        SELECT embedding FROM items WHERE name LIKE '%Web%' LIMIT 1
)
SELECT 
    item_data->>'title' as title,
    item_data->>'authors' as authors,
    embedding <=> (SELECT embedding FROM web_book) as similarity
FROM items
ORDER BY similarity
LIMIT 3;  -- Returns the 3 most similar books

Working with JSON and Vectors ⚡️

JSON Operators

Use ->> to extract text value from a JSON field:

-- Get title from the 'item_data' JSON column
SELECT item_data->>'title' FROM items;

Vector Search Operators

pgvector supports multiple distance functions. Here are the two most commonly used operators.

L2 Distance: `<->`

Measures straight-line (Euclidean) distance between vectors:

-- Find similar books using L2 distance
SELECT 
    name,
    embedding <-> (
        SELECT embedding FROM items WHERE name LIKE '%Web%' LIMIT 1
    ) as distance
FROM items
ORDER BY distance
LIMIT 3;

Cosine Distance: `<=>`

Measures angle-based (cosine) distance between vectors:

-- Find similar books using Cosine distance
SELECT 
    name,
    embedding <=> (
        SELECT embedding FROM items WHERE name LIKE '%Web%' LIMIT 1
    ) as distance
FROM items
ORDER BY distance
LIMIT 3;

💡 Tips

OpenAI recommends <=> (Cosine distance) for their embeddings.
Smaller distance means higher similarity.

Performance Tips 🚀

Query Optimization

Cache query vectors instead of subquerying:

-- ❌ Inefficient: Subquery runs for every row
SELECT name, embedding <=> (
        SELECT embedding FROM items WHERE name LIKE '%Web%' LIMIT 1
) as distance
FROM items
ORDER BY distance
LIMIT 3;

-- ✅ Better: Query vector calculated once
WITH query_embedding AS (
        SELECT embedding FROM items WHERE name LIKE '%Web%' LIMIT 1
)
SELECT 
    name,
    embedding <=> (SELECT embedding FROM query_embedding) as distance
FROM items
ORDER BY distance
LIMIT 3;

Indexing

Choose an index based on your needs:

-- Option 1: IVFFlat (Less memory, good for development)
CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

-- Option 2: HNSW (Faster searches, more memory)
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

Resources 🔗

Hope this helps you build something cool. Feel free to drop a comment below! 💬

Part 1: Setup with PostgreSQL and pgvector

yukaty — Tue, 05 Nov 2024 21:03:40 +0000

Ever wondered how Netflix suggests movies you might like, or how Spotify creates personalized playlists? These AI-powered features often use vector similarity search under the hood. In this series, we'll build our own AI search engine using PostgreSQL with pgvector!

Let's get started...🐢

Project Overview
What is Vector Search?
Step-by-Step Setup
Troubleshooting Tips
Quick Preview
What's Next?

Project Overview ✨

We'll build a search engine to find similar content based on meaning, not just matching keywords. This is the same type of technology behind:

GitHub Copilot's code suggestions
Spotify's song recommendations
Netflix's movie recommendations

While various tools and services support similar functionality, we'll use pgvector to implement vector similarity search within postgreSQL.

In Part 1, we'll set up the database infrastructure. In Part 2, we'll implement the search functionality using OpenAI's embeddings.

What is Vector Search? 🔎

When AI processes content (text, code, or images), it creates a special list of numbers called embedding. Think of it as a smart summary that captures the content's meaning. Similar content will have similar numbers, making it easy to find related items.

If you're not familiar with Machine Learning, don't worry! You can easily obtain these embeddings from AI APIs like OpenAI, even without deep AI knowledge.

pgvector helps us efficiently store and search these embeddings as vectors in PostgreSQL.

Step-by-Step Setup 👣

Make sure you have Docker Desktop installed on your computer.

Project Structure

vector-search/
├── compose.yml
└── postgres/
    └── schema.sql

1. Create `compose.yml`

services:
  db:
    image: pgvector/pgvector:pg17 # PostgreSQL with pgvector support
    container_name: pgvector-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: example_db
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./postgres/schema.sql:/docker-entrypoint-initdb.d/schema.sql

volumes:
  pgdata: # Stores data outside the container to ensure persistence

2. Define Database Schema

Create postgres/schema.sql:

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create sample table
CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    item_data JSONB,
    embedding vector(1536) -- vector data
);

3. Start the Database

Run Docker Compose to build and start the PostgreSQL container with pgvector.

docker compose up --build

4. Verify the Setup

Connect to PostgreSQL:

docker exec -it pgvector-db psql -U postgres -d example_db

Check if everything is set up correctly:

-- Check installed extensions
\dx

-- Check table creation
\dt

-- Check table structure
\d items

Troubleshooting Tips 🛠️

Error: Port 5432 already in use

Change the port in compose.yml to 5433 or another free port.

  ports:
    - "5433:5432"

Database not initializing properly

Remove the volume and restart.

  docker-compose down -v    # Remove existing volume
  docker-compose up --build # Start fresh

Still not sure what's wrong?

Check the container logs.

  docker compose logs db

Quick Preview 👀

Here's a quick preview of how we'll query similar items in Part 2:

-- Find items similar to a specific vector
SELECT id, name, item_data
FROM items
ORDER BY embedding <-> '[0.1, 0.2, ...]'::vector
LIMIT 5;

Replace [0.1, 0.2, ...] with an actual vector from AI models.

What's Next? 💭

We'll dive into the following topics:

Understand what embeddings are and how they work
Generate embeddings using OpenAI
See how vector search works in practice

Stay tuned! 🚀

Spot any mistakes or have a better way? Please leave a comment below! 💬

Understanding Docker with Pizza 🐳🍕

yukaty — Sat, 23 Mar 2024 15:30:45 +0000

Docker is an essential DevOps tool for creating, deploying, and running applications using containers. Let's understand Docker through a pizza restaurant with delivery service! 🛵💨

Contents 📋

Containers & Images
Docker Basics
Your First Container
Troubleshooting
Wrap Up

Containers & Images 📦

Docker Containers: The Delivery Package

A container is like a complete pizza delivery package. Each package includes:

The pizza (your application)
The crust (runtime environment)
The sauce (libraries)
The toppings (dependencies)
The customer data (persistent data/volumes)

Just as customer data is shared across all deliveries but kept separately, Docker volumes store data separately from but connected to your main application.

This complete package ensures a perfect pizza experience anywhere it's delivered, just as Docker containers bundle everything your application needs to run perfectly in any environment. With a delivery driver (Docker Engine) available, your order will always reach customers!

Docker Images: The Recipe Kit

A Docker image is like a standardized pizza recipe with pre-measured ingredients. Once you've perfected this recipe (image), any cook can prepare the exact same pizza for delivery. Just as you can customize toppings before cooking, Docker images can be customized for different environments before running.

Think of it this way: the image is your recipe, while the container is the actual pizza being delivered. You can make many pizzas (run many containers) from one recipe (image)!

Docker Basics 🔰

Core Concepts

Term	Description	Analogy
Dockerfile	Instructions to build a Docker image	Kitchen manual with instructions from prep to packaging
Docker Image	Blueprint for creating containers	Standardized recipe that any cook can follow
Container	Running instance of an application	A complete pizza delivery package ready to go
Volume	Persistent data storage	Customer information

Tools & Services

Term	Description	Pizza Delivery Analogy
Docker Hub	Official repository for sharing images	Central ingredient warehouse
Docker Compose	Tool for running multiple containers together	Restaurant chain management system
Docker Engine	Software that runs containers	Kitchen + Delivery system
Docker Network	System for container communication	Communication between kitchen and drivers

Key Commands

Command	Description	Analogy	Example
`docker build`	Create a new image	Prepare ingredients by recipe	`docker build -t app1 .`
`docker run`	Start a container	Start delivering a pizza	`docker run app1`
`docker stop`	Stop a container	Complete a delivery	`docker stop app1`
`docker ps`	List running containers	Check active deliveries	`docker ps`
`docker logs`	View container output	Check delivery status	`docker logs app1`

Your First Container 👨‍🍳

Just like making a pizza, here's a simple Dockerfile:

# Basic Dockerfile
FROM ubuntu:latest       # Start with base ingredients (base OS)
WORKDIR /app             # Set up kitchen counter (working directory)
COPY ./app .             # Gather ingredients (copy files)
CMD ["./start.sh"]       # Start cooking (run the app)

Troubleshooting 🛠️

# Check container logs
docker logs my_container

# Look inside the container
docker exec -it my_container /bin/bash

Wrap Up 🌯

Docker is a powerful tool that makes application delivery as smooth as a pizza delivery service. We've learned:

Containers are like pizza delivery packages - everything you need in one box
Images are like recipe cards with pre-measured ingredients
Dockerfile is like kitchen manual with exact preparation steps

Feedback and comments are always welcome 💬

Happy containerization! 🐳❤️