Getting Started with WeKnora

This guide will help you get WeKnora up and running quickly. Follow these steps to set up your first knowledge base and start building intelligent Q&A systems.

Prerequisites

Before installing WeKnora, ensure you have the following:

Docker & Docker Compose: WeKnora uses Docker for easy deployment
Git: For cloning the repository
4GB+ RAM: Recommended for running all services
10GB+ Disk Space: For storing documents and indexes

Quick Start (5 Minutes)

The fastest way to get WeKnora running:

Step 1: Clone the Repository

git clone https://github.com/Tencent/WeKnora
cd WeKnora
            

Step 2: Start All Services

./scripts/start_all.sh

This command will:

Start PostgreSQL database
Start vector database
Start backend API server
Start frontend web UI
Start document reader service

Step 3: Access the Web UI

Open your browser and navigate to:

http://localhost

Step 4: Create Your Account

On your first visit, you'll be redirected to the registration page. Create an account to get started.

Creating Your First Knowledge Base

After logging in, follow these steps to create your first knowledge base:

Step 1: Create Knowledge Base

Click "Create Knowledge Base" in the dashboard
Choose between FAQ or Document knowledge base type
Enter a name and description for your knowledge base

Step 2: Configure Models

On the knowledge base configuration page, you'll need to set up:

Embedding Model: For generating vector embeddings
LLM Model: For generating answers (Agent mode or normal mode)
Reranking Model: (Optional) For improving retrieval precision

The Web UI provides an easy interface for model configuration, eliminating the need for manual configuration file editing.

Step 3: Upload Documents

You can upload documents using multiple methods:

Drag and Drop: Simply drag files into the upload area
Folder Import: Import entire folders of documents
URL Import: Import documents from web URLs
Online Entry: Create entries directly in the UI

Step 4: Wait for Processing

The system will automatically:

Parse your documents
Extract text and structure
Generate embeddings
Build indexes

You can track the progress in real-time through the UI.

Step 5: Start Asking Questions

Once processing is complete, you can start asking questions in the conversation interface!

Initialization Configuration

WeKnora now includes a Web UI interface for model configuration, making setup easier than ever.

First-Time Setup Process

If this is your first time using WeKnora:

Start the services: Run ./scripts/start_all.sh
Access Web UI: Navigate to http://localhost
Register: Create your account on the registration page
Create Knowledge Base: Create a new knowledge base
Configure Models: Set up your models on the configuration page

Clearing Existing Data (Optional)

If you need to start fresh with existing data:

# Stop services
./scripts/start_all.sh --stop

# Clear database (only if no important data exists)
make clean-db

# Restart services
./scripts/start_all.sh
            

Development Mode

For developers who need to modify code frequently, use fast development mode to avoid rebuilding Docker images.

Method 1: Using Make Commands (Recommended)

# Start infrastructure
make dev-start

# Start backend (in new terminal)
make dev-app

# Start frontend (in new terminal)
make dev-frontend
            

Method 2: One-Click Start

./scripts/quick-dev.sh

Method 3: Using Scripts

# Start infrastructure
./scripts/dev.sh start

# Start backend (in new terminal)
./scripts/dev.sh app

# Start frontend (in new terminal)
./scripts/dev.sh frontend
            

Development Advantages

Frontend modifications auto hot-reload (no restart needed)
Backend modifications quick restart (5-10 seconds, supports Air hot-reload)
No need to rebuild Docker images
Support IDE breakpoint debugging

Learn More

MCP Server Setup

WeKnora can be accessed via MCP (Model Context Protocol) server for integration with MCP-compatible clients.

Method 1: Direct Python Execution

pip install weknora-mcp-server
python -m weknora-mcp-server
            

Method 2: Configuration File

Configure your MCP client to connect to the server:

{
  "mcpServers": {
    "weknora": {
      "args": [
        "path/to/WeKnora/mcp-server/run_server.py"
      ],
      "command": "python",
      "env": {
        "WEKNORA_API_KEY": "Your API key (starts with sk)",
        "WEKNORA_BASE_URL": "http(s)://your-weknora-address/api/v1"
      }
    }
  }
}
            

Getting Your API Key

Open your WeKnora instance
Open browser developer tools
Check request headers for x-api-key
Copy the key (it starts with "sk")

MCP Documentation

Service Access

Once started, services will be available at:

Web UI: http://localhost
Backend API: http://localhost:8080
Jaeger Tracing: http://localhost:16686

Stopping Services

To stop all WeKnora services:

./scripts/start_all.sh --stop
# Or
make stop-all
            

WeChat Dialog Open Platform

WeKnora serves as the core technology framework for the WeChat Dialog Open Platform, providing a more convenient usage approach:

Zero-code Deployment: Simply upload knowledge to quickly deploy intelligent Q&A services
Efficient Question Management: Support for categorized management of high-frequency questions
WeChat Ecosystem Integration: Seamlessly integrate into WeChat Official Accounts, Mini Programs, and other WeChat scenarios

Next Steps

Now that you have WeKnora running, explore these resources:

Continue Learning

View Documentation See Examples

Troubleshooting

If you encounter issues during setup:

Ensure Docker and Docker Compose are properly installed
Check that ports 80, 8080, and 16686 are not in use
Verify you have sufficient disk space and memory
Check Docker logs for error messages
Review the Troubleshooting FAQ

For additional help, visit our Contact page or check the GitHub Issues.