🚀 Getting Started Guide

Build Your First NLWeb Application

Learn how to set up NLWeb locally and deploy it to Azure. From "Hello World" to production-ready applications in minutes.

Hello World Tutorial

Get NLWeb running on your local machine in under 10 minutes. Perfect for development and testing.

Azure Deployment

Deploy NLWeb to Azure with container instances and managed services for production workloads.

NLWeb Hello World

Set up your first NLWeb instance locally and run your first natural language query

Prerequisites

Required Software

• Python 3.8 or higher
• Git
• OpenAI API key (or other LLM provider)
• Vector database (Qdrant recommended)

Optional Tools

• Docker (for containerized setup)
• VS Code with Python extension
• Azure CLI (for cloud deployment)

Clone the Repository

Get the NLWeb source code from Microsoft's official repository:

# Clone NLWeb repository

git clone https://github.com/microsoft/NLWeb.git

cd NLWeb

Set Up Environment

Create a Python virtual environment and install dependencies:

# Create virtual environment

python -m venv .venv

# Activate environment (Windows)

.venv\Scripts\activate

# Activate environment (macOS/Linux)

source .venv/bin/activate

# Install dependencies

cd code

pip install -r requirements.txt

Configure Environment Variables

Set up your API keys and configuration:

# Copy environment template

cp .env.template .env

Required Environment Variables

OPENAI_API_KEY - Your OpenAI API key

QDRANT_URL - Qdrant instance URL (or use local)

QDRANT_API_KEY - Qdrant API key (if using cloud)

Load Sample Data

Load some sample content to query against:

# Load sample movie data

python -m tools.db_load ../data/json/scifi_movies_schemas.txt scifi_movies

# Or load from RSS feed

python -m tools.db_load https://feeds.libsyn.com/121695/rss Behind-the-Tech

Start NLWeb Server

Launch the NLWeb server and access the web interface:

# Start the server

python app-file.py

# Server will start at http://localhost:8000

🎉 Success!

Visit http://localhost:8000 to access the NLWeb interface. Try asking: "Show me sci-fi movies from the 1980s"

Test Natural Language Queries

Try these example queries to test your setup:

Sample Queries

"Find movies directed by Ridley Scott"

"Show me space operas from the 1970s"

"What are the highest rated sci-fi films?"

API Testing

# Test via curl

curl -X POST \

http://localhost:8000/ask \

-H "Content-Type: application/json" \

-d '{"question": "Find space movies"}'

Deploy NLWeb to Azure

Scale your NLWeb application with Azure's managed services and container infrastructure

Azure Architecture

Container Instances

Deploy NLWeb in Azure Container Instances for serverless scaling

Azure AI Search

Use Azure AI Search as your vector database backend

Azure OpenAI

Integrate with Azure OpenAI for enterprise-grade LLM capabilities

Set Up Azure Resources

Create the required Azure services:

# Login to Azure

az login

# Create resource group

az group create --name nlweb-rg --location eastus

# Create Azure OpenAI service

az cognitiveservices account create \

--name nlweb-openai \

--resource-group nlweb-rg \

--kind OpenAI \

--sku S0 \

--location eastus

Configure Azure AI Search

Set up Azure AI Search as your vector database:

# Create Azure AI Search service

az search service create \

--name nlweb-search \

--resource-group nlweb-rg \

--sku Standard

# Get search service key

az search admin-key show \

--service-name nlweb-search \

--resource-group nlweb-rg

Build and Push Container

Create a container image and push to Azure Container Registry:

# Create container registry

az acr create \

--name nlwebregistry \

--resource-group nlweb-rg \

--sku Basic

# Build and push image

az acr build \

--registry nlwebregistry \

--image nlweb:latest .

Deploy Container Instance

Deploy NLWeb using Azure Container Instances:

# Deploy container instance

az container create \

--resource-group nlweb-rg \

--name nlweb-app \

--image nlwebregistry.azurecr.io/nlweb:latest \

--dns-name-label nlweb-demo \

--ports 8000 \

--environment-variables \

AZURE_OPENAI_ENDPOINT=$OPENAI_ENDPOINT \

AZURE_SEARCH_ENDPOINT=$SEARCH_ENDPOINT

Configure Production Settings

Set up monitoring, scaling, and security for production:

Security

• Use Azure Key Vault for secrets
• Enable managed identity
• Configure HTTPS with custom domain
• Set up network security groups

Monitoring

• Enable Application Insights
• Set up log analytics
• Configure alerts and dashboards
• Monitor API usage and costs

What's Next?

Explore Documentation

Learn about advanced configuration, custom prompts, and integrations.

Try Examples

Explore real-world examples and use cases for different industries.

Join Community

Connect with other developers and contribute to the project.