Verba Cheat Sheet

Overview

Verba is an open-source retrieval-augmented generation chatbot built by Weaviate. It provides a production-ready web interface for uploading documents, querying them with natural language, and getting AI-generated answers grounded in your data. Verba uses Weaviate as its vector database backend and supports multiple LLM providers (OpenAI, Anthropic, Ollama, HuggingFace) and embedding models.

The application handles the full RAG pipeline: document ingestion with chunking, embedding generation, vector storage and retrieval, and LLM-powered answer generation with source citations. Verba is designed as a turnkey solution for teams who want to deploy a document Q&A system without building the RAG infrastructure from scratch.

Installation

pip Install

pip install goldenverba

# Start Verba
verba start
# Access UI at http://localhost:8000

Docker

docker run -p 8000:8000 \
  -e OPENAI_API_KEY=sk-... \
  -e WEAVIATE_URL_VERBA=http://weaviate:8080 \
  weaviate/verba:latest

Docker Compose (with Weaviate)

version: '3.8'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.27.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'none'
      ENABLE_MODULES: ''
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate

  verba:
    image: weaviate/verba:latest
    ports:
      - "8000:8000"
    environment:
      - WEAVIATE_URL_VERBA=http://weaviate:8080
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - weaviate

volumes:
  weaviate_data:

From Source

git clone https://github.com/weaviate/Verba.git
cd Verba
pip install -e .
verba start

Configuration

Environment Variables

Variable	Description	Required
`WEAVIATE_URL_VERBA`	Weaviate instance URL	Yes
`WEAVIATE_API_KEY_VERBA`	Weaviate API key	If auth enabled
`OPENAI_API_KEY`	OpenAI API key	For OpenAI models
`ANTHROPIC_API_KEY`	Anthropic API key	For Claude models
`COHERE_API_KEY`	Cohere API key	For Cohere models
`HUGGINGFACE_API_KEY`	HuggingFace token	For HF models
`UNSTRUCTURED_API_KEY`	Unstructured API key	For advanced parsing

# .env file
WEAVIATE_URL_VERBA=http://localhost:8080
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Component Selection

Component	Options
Embedder	OpenAI, Cohere, HuggingFace, Ollama, SentenceTransformers
Generator	OpenAI, Anthropic, Cohere, Ollama, HuggingFace
Chunker	Token, Sentence, Recursive, Semantic
Reader	Default, Unstructured, PDF, DOCX, CSV
Retriever	Simple, Window, Hybrid

Document Ingestion

Via Web UI

Navigate to http://localhost:8000
Click “Add Documents”
Upload files (PDF, DOCX, TXT, CSV, MD)
Select chunking strategy and embedding model
Click “Import”

Via API

# Upload document
curl -X POST http://localhost:8000/api/import \
  -F "file=@document.pdf" \
  -F "reader=PDFReader" \
  -F "chunker=TokenChunker" \
  -F "embedder=OpenAIEmbedder"

# Upload with metadata
curl -X POST http://localhost:8000/api/import \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "text": "RAG combines retrieval with generation...",
        "metadata": {"source": "wiki", "topic": "AI"},
        "title": "RAG Overview"
      }
    ],
    "chunker": "TokenChunker",
    "embedder": "OpenAIEmbedder"
  }'

Via Python

from goldenverba import VerbaManager
from goldenverba.components.reader import Document

manager = VerbaManager()
manager.connect()

# Create documents
docs = [
    Document(
        text="Retrieval augmented generation combines...",
        metadata={"source": "manual"},
        title="RAG Guide"
    )
]

# Import with specified components
manager.import_documents(
    documents=docs,
    reader="DefaultReader",
    chunker="TokenChunker",
    embedder="OpenAIEmbedder"
)

Querying

Via Web UI

Type questions in the chat interface. Verba displays:

Generated answer
Source document chunks with relevance scores
Document metadata and links

Via API

# Query
curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is retrieval augmented generation?",
    "generator": "OpenAIGenerator",
    "retriever": "SimpleRetriever",
    "top_k": 5
  }'

# Get suggestions (autocomplete)
curl -X POST http://localhost:8000/api/suggestions \
  -H "Content-Type: application/json" \
  -d '{"query": "How does"}'

Via Python

manager = VerbaManager()
manager.connect()

result = manager.query(
    query="Explain the RAG architecture",
    generator="OpenAIGenerator",
    retriever="SimpleRetriever",
    top_k=5
)

print(f"Answer: {result['answer']}")
for chunk in result['context']:
    print(f"Source: {chunk['title']} (score: {chunk['score']:.3f})")

Chunking Strategies

Strategy	Description	Best For
Token	Fixed token-count chunks	General purpose
Sentence	Split by sentence boundaries	Narrative text
Recursive	Hierarchical splitting by separators	Structured documents
Semantic	Group by semantic similarity	Complex documents

Chunker Settings

{
  "chunker": "TokenChunker",
  "config": {
    "chunk_size": 500,
    "chunk_overlap": 50,
    "separator": "\n\n"
  }
}

Advanced Usage

Custom System Prompt

# Via API
curl -X POST http://localhost:8000/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a technical documentation assistant. Answer questions using only the provided context. If the answer is not in the context, say so."
  }'

Hybrid Search

# Combine vector + keyword search
result = manager.query(
    query="database performance optimization",
    retriever="HybridRetriever",
    retriever_config={
        "alpha": 0.75,  # 0=keyword only, 1=vector only
        "top_k": 10
    }
)

Weaviate Direct Access

import weaviate

client = weaviate.Client("http://localhost:8080")

# Query Verba's collection directly
result = client.query.get(
    "Verba_Document",
    ["text", "title", "source"]
).with_near_text({
    "concepts": ["machine learning"]
}).with_limit(5).do()

print(result)

Multi-User Setup

# docker-compose.yml with auth
services:
  weaviate:
    environment:
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'admin-key,readonly-key'
      AUTHENTICATION_APIKEY_USERS: 'admin,reader'
      AUTHORIZATION_ADMINLIST_ENABLED: 'true'
      AUTHORIZATION_ADMINLIST_USERS: 'admin'

Troubleshooting

Issue	Solution
Weaviate connection failed	Check `WEAVIATE_URL_VERBA`, ensure Weaviate is running
Import fails on large PDFs	Increase chunk size, use Unstructured reader
Empty search results	Verify documents were imported, check embedder config
Slow responses	Use faster model (gpt-4o-mini), reduce top_k
Port 8000 in use	Change port: `verba start --port 8001`
API key errors	Check environment variables are set correctly
Docker compose networking	Use service names (e.g., `http://weaviate:8080`)
Memory issues	Increase Docker memory limits for Weaviate

# Check Weaviate health
curl http://localhost:8080/v1/.well-known/ready

# Check Verba health
curl http://localhost:8000/api/health

# View logs
docker compose logs -f verba
docker compose logs -f weaviate

# Reset data
docker compose down -v
docker compose up -d