home / skills / yoanbernabeu / grepai-skills / grepai-embeddings-openai

grepai-embeddings-openai skill

safe

/skills/embeddings/grepai-embeddings-openai

This skill configures OpenAI embeddings for GrepAI, delivering high-quality cloud embeddings for large codebases with scalable performance.

npx playbooks add skill yoanbernabeu/grepai-skills --skill grepai-embeddings-openai

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.1 KB

---
name: grepai-embeddings-openai
description: Configure OpenAI as embedding provider for GrepAI. Use this skill for high-quality cloud embeddings.
---

# GrepAI Embeddings with OpenAI

This skill covers using OpenAI's embedding API with GrepAI for high-quality, cloud-based embeddings.

## When to Use This Skill

- Need highest quality embeddings
- Team environment with shared infrastructure
- Don't want to manage local embedding server
- Willing to trade privacy for quality/convenience

## Considerations

| Aspect | Details |
|--------|---------|
| ✅ **Quality** | State-of-the-art embeddings |
| ✅ **Speed** | Fast, no local compute needed |
| ✅ **Scalability** | Handles any codebase size |
| ⚠️ **Privacy** | Code sent to OpenAI servers |
| ⚠️ **Cost** | Pay per token |
| ⚠️ **Internet** | Requires connection |

## Prerequisites

1. OpenAI API key
2. Billing enabled on OpenAI account

Get your API key at: https://platform.openai.com/api-keys

## Configuration

### Basic Configuration

```yaml
# .grepai/config.yaml
embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
```

Set the environment variable:

```bash
export OPENAI_API_KEY="sk-..."
```

### With Parallel Processing

```yaml
embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
  parallelism: 8  # Concurrent requests for speed
```

### Direct API Key (Not Recommended)

```yaml
embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: sk-your-api-key-here  # Avoid committing secrets!
```

**Warning:** Never commit API keys to version control.

## Available Models

### text-embedding-3-small (Recommended)

| Property | Value |
|----------|-------|
| Dimensions | 1536 |
| Price | $0.00002 / 1K tokens |
| Quality | Very high |
| Speed | Fast |

**Best for:** Most use cases, good balance of cost/quality.

```yaml
embedder:
  provider: openai
  model: text-embedding-3-small
```

### text-embedding-3-large

| Property | Value |
|----------|-------|
| Dimensions | 3072 |
| Price | $0.00013 / 1K tokens |
| Quality | Highest |
| Speed | Fast |

**Best for:** Maximum accuracy, cost not a concern.

```yaml
embedder:
  provider: openai
  model: text-embedding-3-large
  dimensions: 3072
```

### Dimension Reduction

You can reduce dimensions to save storage:

```yaml
embedder:
  provider: openai
  model: text-embedding-3-large
  dimensions: 1024  # Reduced from 3072
```

## Model Comparison

| Model | Dimensions | Cost/1K tokens | Quality |
|-------|------------|----------------|---------|
| `text-embedding-3-small` | 1536 | $0.00002 | ⭐⭐⭐⭐ |
| `text-embedding-3-large` | 3072 | $0.00013 | ⭐⭐⭐⭐⭐ |

## Cost Estimation

Approximate costs per 1000 source files:

| Codebase Size | Chunks | Small Model | Large Model |
|---------------|--------|-------------|-------------|
| Small (100 files) | ~500 | $0.01 | $0.06 |
| Medium (1000 files) | ~5,000 | $0.10 | $0.65 |
| Large (10000 files) | ~50,000 | $1.00 | $6.50 |

**Note:** Costs are one-time for initial indexing. Updates only re-embed changed files.

## Optimizing for Speed

### Parallel Requests

GrepAI v0.24.0+ supports adaptive rate limiting and parallel requests:

```yaml
embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
  parallelism: 8  # Adjust based on your rate limit tier
```

Parallelism recommendations:
- **Tier 1 (Free):** 1-2
- **Tier 2:** 4-8
- **Tier 3+:** 8-16

### Batching

GrepAI automatically batches chunks for efficient API usage.

## Rate Limits

OpenAI has rate limits based on your account tier:

| Tier | RPM | TPM |
|------|-----|-----|
| Free | 3 | 150,000 |
| Tier 1 | 500 | 1,000,000 |
| Tier 2 | 5,000 | 5,000,000 |

GrepAI handles rate limiting automatically with adaptive backoff.

## Environment Variables

### Setting the API Key

**macOS/Linux:**
```bash
# In ~/.bashrc, ~/.zshrc, or ~/.profile
export OPENAI_API_KEY="sk-..."
```

**Windows (PowerShell):**
```powershell
$env:OPENAI_API_KEY = "sk-..."
# Or permanently
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User')
```

### Using .env Files

Create `.env` in your project root:

```
OPENAI_API_KEY=sk-...
```

Add to `.gitignore`:
```gitignore
.env
```

## Azure OpenAI

For Azure-hosted OpenAI:

```yaml
embedder:
  provider: openai
  model: your-deployment-name
  api_key: ${AZURE_OPENAI_API_KEY}
  endpoint: https://your-resource.openai.azure.com
```

## Security Best Practices

1. **Use environment variables:** Never hardcode API keys
2. **Add to .gitignore:** Exclude `.env` files
3. **Rotate keys:** Regularly rotate API keys
4. **Monitor usage:** Check OpenAI dashboard for unexpected usage
5. **Review code:** Ensure sensitive code isn't being indexed

## Common Issues

❌ **Problem:** `401 Unauthorized`
✅ **Solution:** Check API key is correct and environment variable is set:
```bash
echo $OPENAI_API_KEY
```

❌ **Problem:** `429 Rate limit exceeded`
✅ **Solution:** Reduce parallelism or upgrade OpenAI tier:
```yaml
embedder:
  parallelism: 2  # Lower value
```

❌ **Problem:** High costs
✅ **Solutions:**
- Use `text-embedding-3-small` instead of large
- Reduce dimension size
- Add more ignore patterns to reduce indexed files

❌ **Problem:** Slow indexing
✅ **Solution:** Increase parallelism:
```yaml
embedder:
  parallelism: 8
```

❌ **Problem:** Privacy concerns
✅ **Solution:** Use Ollama for local embeddings instead

## Migrating from Ollama to OpenAI

1. Update configuration:
```yaml
embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
```

2. Delete existing index:
```bash
rm .grepai/index.gob
```

3. Re-index:
```bash
grepai watch
```

**Important:** You cannot mix embeddings from different models/providers.

## Output Format

Successful OpenAI configuration:

```
✅ OpenAI Embedding Provider Configured

   Provider: OpenAI
   Model: text-embedding-3-small
   Dimensions: 1536
   Parallelism: 4
   API Key: sk-...xxxx (from environment)

   Estimated cost for this codebase:
   - Files: 245
   - Chunks: ~1,200
   - Cost: ~$0.02

   Note: Code will be sent to OpenAI servers.
```

Overview

This skill configures OpenAI as the embedding provider for GrepAI so you can generate high-quality, cloud-based vector embeddings for semantic code search and analysis. It provides recommended models, configuration snippets, and guidance for performance, cost, and security. Use it when you prefer managed embeddings and scalable indexing over local hosting.

How this skill works

The skill connects GrepAI to OpenAI's embeddings API and uses selected models (e.g., text-embedding-3-small or text-embedding-3-large) to convert code and text chunks into vectors. It supports parallel requests, adaptive batching, and optional dimension reduction to control storage and cost. Configuration is done via .grepai/config.yaml and environment variables for the API key.

When to use it

You want the highest-quality, cloud-hosted embeddings for semantic code search.
Teams with shared infrastructure who prefer not to run local embedding servers.
When fast indexing and easy scalability are priorities.
If you accept that code will be sent to OpenAI servers (privacy trade-off).
When you have billing enabled and are prepared to pay per token.

Best practices

Store API keys in environment variables or .env and add .env to .gitignore; never commit keys.
Start with text-embedding-3-small for cost-effective quality; use large only if accuracy is critical.
Adjust parallelism based on your OpenAI tier to avoid rate limits.
Monitor usage and rotate keys regularly to reduce risk and unexpected costs.
Add ignore patterns to reduce indexed files and lower embedding costs.

Example use cases

Index a codebase for semantic search to quickly find function implementations and references.
Build a code review assistant that finds similar code patterns across repositories.
Create a call-graph or cross-references tool that relies on vector similarity for context.
Migrate from a local embedding provider (e.g., Ollama) to OpenAI for managed performance.
Re-index large codebases with parallelism to shorten initial indexing time.

FAQ

Which model should I choose?

Use text-embedding-3-small for a strong balance of cost and quality; choose text-embedding-3-large if you need maximum accuracy and can accept higher cost.

How do I avoid rate limit errors?

Reduce parallelism, rely on GrepAI's adaptive backoff, or upgrade your OpenAI account tier to increase RPM/TPM limits.

Can I mix embeddings from different providers?

No. Do not mix embeddings from different models or providers; delete the existing index and re-index when changing providers or models.