sever3d/nlp-api

•Updated 7 months ago

Image

1.1K

sever3d/nlp-api repository overview

⁠Embeddings & Vector Search API

NLP API for text validation, toxicity detection, and semantic search using embeddings. Powered by SentenceTransformer, language detection, and toxicity classification models.

⁠Quick Start

docker run -d \
  -p 9050:9050 \
  -e POSTGRES_HOST=postgres.example.com \
  -e POSTGRES_USER=student \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=mscstudents \
  -e POSTGRES_PORT=5432 \
  -e API_TOKEN=my_secure_token \
  --name embedding-api \
  sever3d/embedding-api:latest

⁠Features

Text Embeddings — 768-dimensional vectors via SentenceTransformer
Language Detection — English validation with configurable confidence
Toxicity Classification — Detect harmful content
Semantic Search — Find similar questions using pgvector similarity search
Configurable ML — Adjust thresholds and toggle checks via environment variables

⁠Required Environment Variables

Variable	Required	Default	Description
`POSTGRES_HOST`	Yes	—	PostgreSQL hostname
`POSTGRES_USER`	Yes	—	PostgreSQL username
`POSTGRES_PASSWORD`	Yes	—	PostgreSQL password
`POSTGRES_DB`	Yes	—	Database name
`POSTGRES_PORT`	No	`5432`	PostgreSQL port
`API_TOKEN`	Yes	—	Bearer token for all endpoints
`API_PORT`	No	`9050`	API port
`SEARCH_LIMITS_COUNT`	No	`5`	Default search result limit
`LANG_CONFIDENCE_THRESHOLD`	No	`0.5`	Language detection threshold (0-1)
`TOXICITY_SCORE_THRESHOLD`	No	`0.8`	Toxicity threshold (0-1)
`CHECK_TOXICITY_DEFAULT`	No	`true`	Enable toxicity check by default

⁠Requirements

PostgreSQL 13+ with pgvector extension enabled
2GB+ available memory for ML models (downloaded on first run)
Network access to HuggingFace for model downloads (~1.5GB)

⁠Docker Compose Example

version: "3.9"

services:
  postgres:
    image: pgvector/pgvector:pg13
    environment:
      POSTGRES_USER: student
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mscstudents
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./postgres/init:/docker-entrypoint-initdb.d:ro
    ports:
      - "5432:5432"

  embedding-api:
    image: sever3d/embedding-api:latest
    ports:
      - "9050:9050"
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_USER: student
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mscstudents
      POSTGRES_PORT: 5432
      API_TOKEN: my_secure_token
      API_PORT: 9050
    volumes:
      - hf_models:/models
    depends_on:
      - postgres

volumes:
  postgres_data:
  hf_models:

⁠Database Initialization

Required PostgreSQL extensions:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE IF NOT EXISTS question_embeddings (
    question_id text PRIMARY KEY,
    question text NOT NULL,
    embedding vector(768) NOT NULL
);

CREATE INDEX IF NOT EXISTS question_embeddings_embedding_hnsw_idx
ON question_embeddings
USING hnsw (embedding vector_cosine_ops);

Include these SQL files in PostgreSQL initialization directory (mounted at /docker-entrypoint-initdb.d).

⁠API Endpoints

All endpoints require x-access-tokens header.

⁠Health Check

curl -H "x-access-tokens: my_secure_token" \
  http://localhost:9050/healthcheck

Response:

{"status": "OK"}

⁠Generate Embedding

POST /embedding

Generate 768-dimensional embedding for text.

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}' \
  http://localhost:9050/embedding

Response:

{
  "embedding": [0.123, -0.456, 0.789, ...]
}

⁠Validate Text (Language + Toxicity)

POST /validatetext

Check if text is English. Optionally detect toxicity.

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is good content",
    "check_toxicity": true
  }' \
  http://localhost:9050/validatetext

Response:

{"valid": true}

Payload:

text (required) — Text to validate
check_toxicity (optional) — Override default toxicity check

⁠Get Toxicity Score

POST /toxicity

Score text for toxicity (0-1, higher = more toxic).

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"text": "Some content"}' \
  http://localhost:9050/toxicity

Response:

{"score": 0.05}

⁠Store Question Embedding

POST /embedding/mongostore

Generate embedding and store in PostgreSQL.

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{
    "questionId": "q1",
    "question": "What is artificial intelligence?"
  }' \
  http://localhost:9050/embedding/mongostore

Response:

{
  "questionId": "q1",
  "question": "What is artificial intelligence?",
  "question_embedding": [0.123, -0.456, ...]
}

⁠Semantic Search

POST /embedding/search

Find similar stored questions by semantic similarity.

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"question": "machine learning basics"}' \
  "http://localhost:9050/embedding/search?limit=5"

Response:

[
  {
    "questionId": "q1",
    "question": "What is artificial intelligence?"
  },
  {
    "questionId": "q3",
    "question": "How does deep learning work?"
  }
]

Query Parameters:

limit (optional) — Number of results (default: SEARCH_LIMITS_COUNT)

⁠Validate Question

POST /validate/question

Validate both title and body (language + toxicity).

curl -X POST \
  -H "x-access-tokens: my_secure_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to learn programming?",
    "body": "I want to start learning Python and JavaScript."
  }' \
  http://localhost:9050/validate/question

Response:

{
  "valid_english_title": true,
  "valid_english_body": true,
  "toxicity_score_title": 0.02,
  "toxicity_score_body": 0.01
}

⁠Performance

First request: ~30-60 seconds (models download from HuggingFace, ~1.5GB)
Subsequent requests: ~100-500ms (models cached)
Embeddings: 768 dimensions, cosine similarity search
Memory: 2GB+ recommended

⁠Models

sentence-transformers/all-mpnet-base-v2 — Text embeddings
papluca/xlm-roberta-base-language-detection — Language detection
unitary/toxic-bert — Toxicity classification

⁠Limitations

English only — Non-English text rejected at language detection
Offline mode — Requires internet for model downloads on first run
Stateful — Models cached in volume; ensure persistence across restarts

⁠License

Use it, but be kind to mention my repo name and maybe Github as well ?

Tag summary

Recent tags

Content type

Image

Digest

sha256:60aea4c30…

Size

4.1 GB

Last updated

7 months ago

docker pull sever3d/nlp-api