Website | Documentation | Demos | Slack Community | Marqo Cloud

A tensor-based search and analytics engine that seamlessly integrates with applications and websites. Marqo allows developers to turbocharge search functionality with the latest machine learning models, in 3 lines of code.

Try the demo | View the code

✨ Core Features

⚡ Performance

• Embeddings stored in in-memory HNSW indexes, achieving cutting edge search speeds.
• Scale to hundred-million document indexes with horizontal index sharding.
• Async and non-blocking data upload and search.

🤖 Machine Learning

• Use the latest machine learning models from PyTorch, Huggingface, OpenAI and more.
• Start with a pre-configured model or bring your own.
• Built in ONNX support and conversion for faster inference and higher throughput.
• CPU and GPU support.

☁️ Cloud-native

• Fast deployment using Docker.
• Run Marqo multi-az and high availability.

🌌 End-to-end

• Build search and analytics on multiple unstructured data types such as text, image, code, video.
• Filter search results using Marqo’s query DSL.
• Store unstructred data and semi-structured metadata together in documents, using a range of supported datatypes like bools, ints and keywords.

🍱 Managed cloud

• Scale Marqo at the click of a button.
• Multi-az, accelerated inference.
• Marqo cloud ☁️ is in beta. If you’re interested, apply here.

Learn more about Marqo

📗 Quick start	Build your first application with Marqo in under 5 minutes.
🔍 What is tensor search?	A beginner's guide to the fundamentals of Marqo and tensor search.
🖼 Marqo for image data	Building text-to-image search in Marqo in 5 lines of code.
📚 Marqo for text	Building a multilingual database in Marqo.
🔮 Integrating Marqo with GPT	Making GPT a subject matter expert by using Marqo as a knowledge base.
🎨 Marqo for Creative AI	Combining stable diffusion with semantic search to generate and categorise 100k images of hotdogs.
🦾 Features	Marqo's core features.

Getting started

1. Marqo requires docker. To install Docker go to the Docker Official website. Ensure that docker has at least 8GB memory and 50GB storage.

2. Use docker to run Marqo (Mac users with M-series chips will need to go here):

docker rm -f marqo
docker pull marqoai/marqo:latest
docker run --name marqo -it --privileged -p 8882:8882 --add-host host.docker.internal:host-gateway marqoai/marqo:latest

3. Install the Marqo client:

pip install marqo

4. Start indexing and searching! Let's look at a simple example below:

import marqo

mq = marqo.Client(url='http://localhost:8882')

mq.index("my-first-index").add_documents([
    {
        "Title": "The Travels of Marco Polo",
        "Description": "A 13th-century travelogue describing Polo's travels"
    }, 
    {
        "Title": "Extravehicular Mobility Unit (EMU)",
        "Description": "The EMU is a spacesuit that provides environmental protection, "
                       "mobility, life support, and communications for astronauts",
        "_id": "article_591"
    }]
)

results = mq.index("my-first-index").search(
    q="What is the best outfit to wear on the moon?", searchable_attributes=["Title", "Description"]
)

• mq is the client that wraps the marqo API
• add_documents() takes a list of documents, represented as python dicts for indexing.
• add_documents() creates an index with default settings, if one does not already exist.
• You can optionally set a document's ID with the special _id field. Otherwise, Marqo will generate one.
• If the index doesn't exist, Marqo will create it. If it exists then Marqo will add the documents to the index.

Let's have a look at the results:

# let's print out the results:
import pprint
pprint.pprint(results)

{
    'hits': [
        {   
            'Title': 'Extravehicular Mobility Unit (EMU)',
            'Description': 'The EMU is a spacesuit that provides environmental protection, mobility, life support, and' 
                           'communications for astronauts',
            '_highlights': {
                'Description': 'The EMU is a spacesuit that provides environmental protection, '
                               'mobility, life support, and communications for astronauts'
            },
            '_id': 'article_591',
            '_score': 0.61938936
        }, 
        {   
            'Title': 'The Travels of Marco Polo',
            'Description': "A 13th-century travelogue describing Polo's travels",
            '_highlights': {'Title': 'The Travels of Marco Polo'},
            '_id': 'e00d1a8d-894c-41a1-8e3b-d8b2a8fce12a',
            '_score': 0.60237324
        }
    ],
    'limit': 10,
    'processingTimeMs': 49,
    'query': 'What is the best outfit to wear on the moon?'
}

• Each hit corresponds to a document that matched the search query.
• They are ordered from most to least matching.
• limit is the maximum number of hits to be returned. This can be set as a parameter during search.
• Each hit has a _highlights field. This was the part of the document that matched the query the best.

Other basic operations

Get document

Retrieve a document by ID.

result = mq.index("my-first-index").get_document(document_id="article_591")

Note that by adding the document using add_documents again using the same _id will cause a document to be updated.

Get index stats

Get information about an index.

results = mq.index("my-first-index").get_stats()

Lexical search

Perform a keyword search.

result = mq.index("my-first-index").search('marco polo', search_method=marqo.SearchMethods.LEXICAL)

Search specific fields

Using the default tensor search method.

result = mq.index("my-first-index").search('adventure', searchable_attributes=['Title'])

Delete documents

Delete documents.

results = mq.index("my-first-index").delete_documents(ids=["article_591", "article_602"])

Delete index

Delete an index.

results = mq.index("my-first-index").delete()

Multi modal and cross modal search

To power image and text search, Marqo allows users to plug and play with CLIP models from HuggingFace. Note that if you do not configure multi modal search, image urls will be treated as strings. To start indexing and searching with images, first create an index with a CLIP configuration, as below:

settings = {
  "treat_urls_and_pointers_as_images":True,   # allows us to find an image file and index it 
  "model":"ViT-L/14"
}
response = mq.create_index("my-multimodal-index", **settings)

Images can then be added within documents as follows. You can use urls from the internet (for example S3) or from the disk of the machine:

response = mq.index("my-multimodal-index").add_documents([{
    "My Image": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f2/Portrait_Hippopotamus_in_the_water.jpg/440px-Portrait_Hippopotamus_in_the_water.jpg",
    "Description": "The hippopotamus, also called the common hippopotamus or river hippopotamus, is a large semiaquatic mammal native to sub-Saharan Africa",
    "_id": "hippo-facts"
}])

Setting searchable_attributes to the image field ['My Image'] ensures only images are searched in this index:

results = mq.index("my-multimodal-index").search('animal',  searchable_attributes=['My Image'])

You can then search using text as usual. Both text and image fields will be searched:

results = mq.index("my-multimodal-index").search('animal')

Setting searchable_attributes to the image field ['My Image'] ensures only images are searched in this index:

results = mq.index("my-multimodal-index").search('animal', searchable_attributes=['My Image'])

Searching using an image

Searching using an image can be achieved by providing the image link.

results = mq.index("my-multimodal-index").search('https://upload.wikimedia.org/wikipedia/commons/thumb/9/96/Standing_Hippopotamus_MET_DP248993.jpg/440px-Standing_Hippopotamus_MET_DP248993.jpg')

Documentation

The full documentation for Marqo can be found here https://docs.marqo.ai/.

Warning

Note that you should not run other applications on Marqo's Opensearch cluster as Marqo automatically changes and adapts the settings on the cluster.

M series Mac users

Marqo does not yet support the docker-in-docker backend configuration for the arm64 architecture. This means that if you have an M series Mac, you will also need to run marqo's backend, marqo-os, locally.

To run Marqo on an M series Mac, follow the next steps.

1. In one terminal run the following command to start opensearch:

docker rm -f marqo-os; docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" marqoai/marqo-os:0.0.3-arm

2. In another terminal run the following command to launch Marqo:

docker rm -f marqo; docker run --name marqo --privileged \
    -p 8882:8882 --add-host host.docker.internal:host-gateway \
    -e "OPENSEARCH_URL=https://localhost:9200" \
    marqoai/marqo:latest

Contributors

Marqo is a community project with the goal of making tensor search accessible to the wider developer community. We are glad that you are interested in helping out! Please read this to get started.

Dev set up

1. Create a virtual env python -m venv ./venv.

2. Activate the virtual environment source ./venv/bin/activate.

3. Install requirements from the requirements file: pip install -r requirements.txt.

4. Ensure you have marqo-os running with docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" --name marqo-os marqoai/marqo-os:0.0.3

5. Run tests by running the tox file. CD into this dir and then run "tox".

6. If you update dependencies, make sure to delete the .tox dir and rerun.

Merge instructions:

1. Run the full test suite (by using the command tox in this dir).

2. Create a pull request with an attached github issue.

Support

• Join our Slack community and chat with other community members about ideas.
• Marqo community meetings (coming soon!).

Stargazers

.

Forkers

.

Translations

This readme is available in the following translations:

• English🇬🇧
• Français🇫🇷
• 中文 Chinese🇨🇳
• Polski🇵🇱
• Українська🇺🇦