AI Setup

ChartDB’s AI features enable intelligent DDL script generation for easy database migrations. You can use OpenAI’s GPT models or self-hosted LLM inference servers.

What AI Features Do

ChartDB’s AI capabilities include:

DDL Export

Generate DDL scripts in any database dialect for migrations

Smart Conversion

Convert schemas between MySQL, PostgreSQL, SQLite, SQL Server, etc.

Dialect Translation

Translate database-specific syntax to your target platform

Schema Optimization

Get suggestions for schema improvements and best practices

AI features are completely optional. ChartDB works perfectly without AI for schema visualization and manual editing.

Option 1: OpenAI API

The simplest way to enable AI features is using OpenAI’s API.

Get an API Key

Create OpenAI Account

Add Payment Method

Navigate to Billing → Payment methods and add a payment method

Generate API Key

Go to API Keys → Create new secret key

Copy the key immediately - you won’t be able to see it again!

Set Usage Limits

Under Billing → Usage limits, set a monthly budget to prevent unexpected charges

Configure ChartDB

Docker Runtime
Docker Build
NPM Development
NPM Build

Pass the API key when running the container:

docker run \
  -e OPENAI_API_KEY=sk-proj-your-key-here \
  -p 8080:80 \
  ghcr.io/chartdb/chartdb:latest

Recommended: Runtime configuration keeps secrets out of images

Embed the API key during build:

docker build \
  --build-arg VITE_OPENAI_API_KEY=sk-proj-your-key-here \
  -t chartdb .

docker run -p 8080:80 chartdb

The API key will be embedded in the image. Use runtime configuration for production.

Set the environment variable before running:

# Linux/Mac
export VITE_OPENAI_API_KEY=sk-proj-your-key-here
npm run dev

# Or inline
VITE_OPENAI_API_KEY=sk-proj-your-key-here npm run dev

# Windows PowerShell
$env:VITE_OPENAI_API_KEY="sk-proj-your-key-here"
npm run dev

Build with the API key:

VITE_OPENAI_API_KEY=sk-proj-your-key-here npm run build
npm run preview

Test the Configuration

Open ChartDB

Navigate to http://localhost:8080 (or your configured port)

Create or Import Schema

Create a new diagram or import an existing database schema

Export with AI

Click Export → AI-Powered Export and select a target database

Verify Output

You should see a DDL script generated for your target database dialect

If AI features aren’t working, check the browser console (F12) for error messages about the API key.

Option 2: Self-Hosted LLM

For complete data privacy or to avoid API costs, use a self-hosted LLM inference server.

Supported Inference Servers

Any server compatible with OpenAI’s API format will work:

vLLM
Ollama
LocalAI
LM Studio

High-performance inference server optimized for throughput.Installation:

pip install vllm

Run Server:

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-32B-Instruct-AWQ \
  --port 8000

Configure ChartDB:

docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:8000/v1 \
  -e LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ \
  -p 8080:80 \
  ghcr.io/chartdb/chartdb:latest

vLLM is excellent for high-throughput scenarios and supports many quantization formats (AWQ, GPTQ, etc.)

Easy-to-use local LLM server with simple setup.Installation:

# Download from ollama.ai
curl -fsSL https://ollama.ai/install.sh | sh

Run Server:

# Pull a model
ollama pull llama3.1

# Server starts automatically
# Ollama uses port 11434 by default

Configure ChartDB:

docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:11434/v1 \
  -e LLM_MODEL_NAME=llama3.1 \
  -p 8080:80 \
  ghcr.io/chartdb/chartdb:latest

Ollama is the easiest option for local LLMs with automatic model management.

Drop-in replacement for OpenAI API with many model formats.Installation:

docker run -p 8080:8080 \
  -v $PWD/models:/models \
  localai/localai:latest

Configure ChartDB:

docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:8080/v1 \
  -e LLM_MODEL_NAME=gpt-3.5-turbo \
  -p 8081:80 \
  ghcr.io/chartdb/chartdb:latest

LocalAI supports GGUF, GGML, and other quantized formats. Check their docs for model configuration.

Desktop application with built-in model browser and API server.Setup:

Download from lmstudio.ai
Search and download a model (e.g., “Qwen 2.5”)
Load the model
Click Start Server (usually port 1234)

Configure ChartDB:

docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:1234/v1 \
  -e LLM_MODEL_NAME=qwen2.5-7b-instruct \
  -p 8080:80 \
  ghcr.io/chartdb/chartdb:latest

LM Studio is perfect for desktop users who want a GUI for model management.

Recommended Models

For DDL generation and schema conversion, these models work well:

Model	Size	Quality	Speed	Memory
Qwen 2.5 32B	32B	Excellent	Medium	20GB+
Qwen 2.5 14B	14B	Very Good	Fast	10GB+
Qwen 2.5 7B	7B	Good	Very Fast	6GB+
Llama 3.1 70B	70B	Excellent	Slow	40GB+
Llama 3.1 8B	8B	Good	Very Fast	6GB+
Mistral 7B	7B	Good	Very Fast	6GB+

Use quantized models (AWQ, GPTQ, or GGUF) to reduce memory requirements. A 32B AWQ model can run in ~20GB RAM instead of 64GB.

Configuration Examples

Complete vLLM Setup

# 1. Start vLLM server
docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-32B-Instruct-AWQ \
  --quantization awq

# 2. Build ChartDB with vLLM config
docker build \
  --build-arg VITE_OPENAI_API_ENDPOINT=http://localhost:8000/v1 \
  --build-arg VITE_LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ \
  --build-arg VITE_DISABLE_ANALYTICS=true \
  -t chartdb-vllm .

# 3. Run ChartDB (use host network on Linux)
docker run --network host chartdb-vllm

# Or on Mac/Windows:
docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:8000/v1 \
  -e LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ \
  -p 8080:80 \
  chartdb-vllm

Ollama with Docker Compose

docker-compose.yml

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    restart: unless-stopped

  chartdb:
    image: ghcr.io/chartdb/chartdb:latest
    ports:
      - "8080:80"
    environment:
      - OPENAI_API_ENDPOINT=http://ollama:11434/v1
      - LLM_MODEL_NAME=llama3.1
      - HIDE_CHARTDB_CLOUD=true
      - DISABLE_ANALYTICS=true
    depends_on:
      - ollama
    restart: unless-stopped

volumes:
  ollama_data:

# Start services
docker-compose up -d

# Pull model into Ollama
docker-compose exec ollama ollama pull llama3.1

# Access ChartDB
open http://localhost:8080

Network Configuration

When running both the LLM server and ChartDB in Docker:

Linux
Mac/Windows
Docker Compose

Use --network host for simplest setup:

# LLM server
docker run --network host vllm/vllm-openai:latest --model ...

# ChartDB
docker run --network host \
  -e OPENAI_API_ENDPOINT=http://localhost:8000/v1 \
  -e LLM_MODEL_NAME=your-model \
  chartdb

Use host.docker.internal to reach host machine:

# LLM server on host
python -m vllm.entrypoints.openai.api_server --model ... --port 8000

# ChartDB in Docker
docker run \
  -e OPENAI_API_ENDPOINT=http://host.docker.internal:8000/v1 \
  -e LLM_MODEL_NAME=your-model \
  -p 8080:80 \
  chartdb

Use service names for networking:

services:
  vllm:
    image: vllm/vllm-openai:latest
    ports:
      - "8000:8000"
  
  chartdb:
    image: ghcr.io/chartdb/chartdb:latest
    environment:
      # Use service name
      - OPENAI_API_ENDPOINT=http://vllm:8000/v1
      - LLM_MODEL_NAME=your-model

Hybrid Setup

You can switch between OpenAI and self-hosted LLMs by changing environment variables:

# Use OpenAI during development
docker run -e OPENAI_API_KEY=sk-... -p 8080:80 chartdb

# Switch to self-hosted for production
docker run \
  -e OPENAI_API_ENDPOINT=http://vllm:8000/v1 \
  -e LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ \
  -p 8080:80 chartdb

Never configure both options simultaneouslyUse either:

OPENAI_API_KEY (for OpenAI)

OR:

OPENAI_API_ENDPOINT + LLM_MODEL_NAME (for self-hosted)

Configuring both will cause conflicts.

AI Feature Usage

Once configured, use AI features in ChartDB:

Create/Import Schema

Create a new diagram or import your database schema using the Smart Query

Open Export

Click the Export button in the top toolbar

Select AI Export

Choose AI-Powered Export from the export options

Choose Target Database

Select your target database dialect:

PostgreSQL
MySQL
SQL Server
MariaDB
SQLite
CockroachDB
ClickHouse

Generate DDL

The AI will generate optimized DDL scripts for your target database

Review & Copy

Review the generated script and copy it for use in your migration

Troubleshooting

AI features not appearing

Cause: Environment variables not set correctlySolution:

# Check container environment
docker exec <container-id> env | grep -E 'OPENAI|LLM'

# Verify config.js endpoint
curl http://localhost:8080/config.js

# Check browser console (F12) for errors

Ensure you’re using the correct variable names (no VITE_ prefix for runtime).

Cannot connect to inference server

Cause: Network configuration or incorrect endpointSolution:

# Test from ChartDB container
docker exec <container-id> wget -O- http://your-endpoint/v1/models

# For localhost servers, use correct hostname:
# - Linux: http://localhost:8000/v1
# - Mac/Windows: http://host.docker.internal:8000/v1
# - Docker Compose: http://service-name:8000/v1

Verify the endpoint is accessible from the ChartDB container.

Model not found error

Cause: Model name doesn’t match what’s loaded in the serverSolution:

# Check available models
curl http://localhost:8000/v1/models

# Ensure LLM_MODEL_NAME matches exactly
# For vLLM, use the full model path:
-e LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ

# For Ollama, use the model name:
-e LLM_MODEL_NAME=llama3.1

Slow or timeout errors

Cause: Model is too large or not enough resourcesSolution:

Use a smaller/quantized model (7B instead of 32B)
Increase memory allocation for Docker
Use GPU acceleration if available
Increase timeout in your inference server

# vLLM with GPU
docker run --gpus all vllm/vllm-openai:latest --model ...

# Increase Docker memory (Docker Desktop)
# Settings → Resources → Memory → 16GB+

Poor quality DDL output

Cause: Model too small or not suited for code generationSolution:

Use larger models (14B+ recommended)
Try Qwen 2.5 series (optimized for code)
Ensure model supports instruction following
Check if quantization is too aggressive (Q4 vs Q8)

Recommended models for best results:

Qwen 2.5 32B Instruct (AWQ)
Qwen 2.5 14B Instruct
Llama 3.1 70B Instruct

Mixed configuration error

Cause: Both OpenAI and custom endpoint configuredSolution:

# Remove one configuration set

# Option 1: OpenAI only
docker run -e OPENAI_API_KEY=sk-... chartdb

# Option 2: Custom endpoint only
docker run \
  -e OPENAI_API_ENDPOINT=http://... \
  -e LLM_MODEL_NAME=... \
  chartdb

# NOT: Both together

Performance Optimization

Hardware Requirements

For self-hosted LLMs:

Model Size	RAM Required	GPU Memory	Speed
7B (Q4)	6 GB	4 GB	Fast
7B (Q8)	8 GB	6 GB	Fast
14B (AWQ)	10 GB	8 GB	Medium
32B (AWQ)	20 GB	16 GB	Medium
70B (AWQ)	40 GB	32 GB	Slow

AWQ and GPTQ quantization provide the best quality-to-size ratio. Q4 is fast but lower quality.

Optimization Tips

Use Quantization

AWQ or GPTQ models offer 2-3x memory reduction with minimal quality loss

GPU Acceleration

Use --gpus all with vLLM or enable GPU in LM Studio for 10-50x speedup

Batch Inference

vLLM automatically batches requests for better throughput

Model Caching

Keep models loaded in memory to avoid reload overhead

Security & Privacy

Self-hosted LLMs provide complete data privacy:

Benefits of Self-Hosting:

Schema data never leaves your network
No external API calls
Full audit trail
No usage limits or costs
Compliance with data regulations (GDPR, HIPAA, etc.)

Best Practices:

Network Isolation

Run LLM servers on isolated networks with no internet access

Access Control

Use authentication for inference server APIs in production

Monitoring

Log all AI requests for audit purposes

Model Validation

Verify model sources and checksums before deployment

Cost Comparison

Option	Setup Cost	Running Cost	Privacy	Performance
OpenAI API	Free	~$0.01-0.10 per request	⚠️ Data sent to OpenAI	Fast (API latency)
Self-hosted (CPU)	Free	~$0.50/hr server cost	✅ Complete privacy	Slow (CPU inference)
Self-hosted (GPU)	$500-5000 hardware	~$0.10-1.00/hr electricity	✅ Complete privacy	Fast (GPU inference)
Cloud GPU (AWS/GCP)	Free	~$1-5/hr instance cost	⚠️ Data in cloud	Fast (GPU inference)

For occasional use, OpenAI API is most cost-effective. For frequent use or privacy requirements, self-hosted is better.

Get Started

Core Features

Database Support

Guides

Self-Hosting

What AI Features Do

DDL Export

Smart Conversion

Dialect Translation

Schema Optimization

Option 1: OpenAI API

Get an API Key

Configure ChartDB

Test the Configuration

Option 2: Self-Hosted LLM

Supported Inference Servers

Recommended Models

Configuration Examples

Complete vLLM Setup

Ollama with Docker Compose

Network Configuration

Hybrid Setup

AI Feature Usage

Troubleshooting

Performance Optimization

Hardware Requirements

Optimization Tips

Use Quantization

GPU Acceleration

Batch Inference

Model Caching

Security & Privacy

Cost Comparison

Next Steps

Docker Deployment

Configuration

Get Started

Core Features

Database Support

Guides

Self-Hosting

​What AI Features Do

DDL Export

Smart Conversion

Dialect Translation

Schema Optimization

​Option 1: OpenAI API

​Get an API Key

​Configure ChartDB

​Test the Configuration

​Option 2: Self-Hosted LLM

​Supported Inference Servers

​Recommended Models

​Configuration Examples

​Complete vLLM Setup

​Ollama with Docker Compose

​Network Configuration

​Hybrid Setup

​AI Feature Usage

​Troubleshooting

​Performance Optimization

​Hardware Requirements

​Optimization Tips

Use Quantization

GPU Acceleration

Batch Inference

Model Caching

​Security & Privacy

​Cost Comparison

​Next Steps

Docker Deployment

Configuration

What AI Features Do

Option 1: OpenAI API

Get an API Key

Configure ChartDB

Test the Configuration

Option 2: Self-Hosted LLM

Supported Inference Servers

Recommended Models

Configuration Examples

Complete vLLM Setup

Ollama with Docker Compose

Network Configuration

Hybrid Setup

AI Feature Usage

Troubleshooting

Performance Optimization

Hardware Requirements

Optimization Tips

Security & Privacy

Cost Comparison

Next Steps