Getting Started

The fastest way to get started with Amgix is to use Amgix One, a single-container deployment that bundles the API, encoders, RabbitMQ, and Qdrant database.

1. Start Amgix One

Run the following command to start Amgix One. It will expose the API on port 8234 and mount a local directory to persist your data and cached models.

docker run -d -p 8234:8234 -v /path/on/host:/data amgixio/amgix-one:1

Note: Replace /path/on/host with an actual path on your machine where you want to store the data.

Use the short tag 1 for the latest 1.x release, or a specific version from Releases (e.g. amgixio/amgix-one:v1.0.0). For GPU support use amgixio/amgix-one:1-gpu (requires NVIDIA Container Toolkit).

2. Define a Collection

Create a collection to store your documents. We'll configure it with a keyword vector (wmtr) and a semantic dense vector using a Hugging Face model.

curl -X POST http://localhost:8234/v1/collections/products \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "name": "keyword",
        "type": "keyword",
        "index_fields": ["name", "content"]
      },
      {
        "name": "semantic",
        "type": "dense_model",
        "model": "sentence-transformers/all-MiniLM-L6-v2",
        "index_fields": ["content"]
      }
    ]
  }'

Note: The first time you create a collection with a new model, Amgix will download the model weights, which may take a few seconds.

3. Upload Documents

Now, upload a few documents to your new collection using the bulk upload endpoint. The system will automatically queue them and generate the required embeddings in the background.

curl -X POST http://localhost:8234/v1/collections/products/documents/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "part-001",
        "timestamp": "2026-03-15T00:00:00Z",
        "name": "Roller 12LP'\''-x03/5-XL",
        "content": "Precision pinch roller assembly for manufacturing."
      },
      {
        "id": "part-002",
        "timestamp": "2026-03-15T00:00:00Z",
        "name": "Bearing 12LP'\''-y03/5-XL",
        "content": "Deep groove ball bearing, double shielded."
      },
      {
        "id": "part-003",
        "timestamp": "2026-03-15T00:00:00Z",
        "name": "Belt 12LP'\''-x03/8-MD",
        "content": "Synchronous timing belt for power transmission."
      }
    ]
  }'

4. Test the Search

Amgix automatically fuses results from both the keyword and semantic vectors. Let's test both capabilities.

Query 1: The Keyword Test

Imagine a user only has a partial part number from a smudged label or a fragmented manifest, and there are many items with very similar identifiers. What if they type it without punctuation?

curl -X POST http://localhost:8234/v1/collections/products/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "12lpy03",
    "limit": 1
  }'

Result: Amgix returns part-002. Standard full-text search relies on punctuation to create tokens, so searching for 12lpy03 against 12LP'-y03/5-XL usually returns zero results. Amgix's built-in keyword tokenizer (WMTR) matches across token boundaries effortlessly to find the exact right part.

Query 2: The Semantic Test

Now search for a concept where the exact words don't exist in the document:

curl -X POST http://localhost:8234/v1/collections/products/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "motor energy transfer loop",
    "limit": 1
  }'

Result: Amgix returns part-003! Notice that the words "motor", "energy", "transfer", and "loop" do not appear anywhere in that document (it says "Synchronous timing belt for power transmission"). The semantic ML model understands the concept, while the keyword vector handles exact matches. This is true hybrid search.

API Documentation

Amgix automatically generates OpenAPI documentation. Once your server is running, you can explore the full API reference and test endpoints interactively by visiting:

http://localhost:8234/docs

---

Next Steps: - Read about What We Think is Cool About Amgix - Learn Why We Built Amgix