StarSpace Documentation

Use ImageSpace to learn joint embeddings between images and other entities (like words or hashtags). You can represent images using features from a pre-trained model (e.g., the last layer of a ResNet).

Input Format: Convert image features into a space-separated format where each dimension is prefixed by its index, followed by the label: d0:0.8 d1:0.5 ... d1023:1.2 __label__1

$bash examples/image_feature_example_cifar10.sh

Use GraphSpace to learn mappings between entities and relations in knowledge bases (e.g., Freebase). This is used for link prediction, such as predicting a tail_entity given a head_entity and a relation_type.

For each relation_type, the model learns two embeddings: one for predicting the tail given the head, and one for predicting the head given the tail.

$bash examples/multi_relation_example.sh

Use DocSpace to embed and recommend web documents based on user click or like history.

Each document is represented as a bag-of-words. Each user is represented as a bag of documents they have interacted with.

Input Format: Each line represents a user. Documents within that line must be separated by tabs (\t): doc_1_word1 doc_1_word2 \t doc_2_word1 \t doc_3_word1

Training Logic: Set -trainMode 1 and -fileFormat labelDoc. At each training step, one random document from the user's history is selected as the label, and the rest are used as input.

./starspace train -trainFile input.txt -model docspace -trainMode 1 -fileFormat labelDoc

Use ArticleSpace to learn the mapping between sentences and the articles they belong to. This allows finding the most relevant articles for a given sentence.

Training Logic: Set -trainMode 2. Each training example is an article containing multiple sentences. At training time, one sentence is picked at random as the input, the remaining sentences in that article become the label, and sentences from other articles are used as random negatives.

$bash examples/wikipedia_article_search.sh

Use SentenceSpace to learn mappings between sentences so that semantically similar sentences can be found in the same embedding space.

Training Logic: Set -trainMode 3. Each training example is a collection of semantically related sentences. At each step, two sentences are picked at random: one as input and one as the label. Other sentences in the collection are used as random negatives.

$bash examples/wikipedia_sentence_matching.sh

To use the Starwrap Python wrapper, you must build it from source.

Prerequisites:

• CMake: Must be installed on your system.
• Conan: C++ package manager must be installed.

Build Steps:

1. Clone the repository.
2. Navigate to the python directory.
3. Execute the build script:

chmod +x build.sh
./build.sh

The build script downloads necessary packages, builds the wrapper, and runs test code. Upon completion, a starwrap.so file will be generated in a new build directory.

Integration: To use the module in your Python project, you can either:

• Copy starwrap.so directly into your project directory.
• Add the directory containing starwrap.so to your LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS).

Prerequisites

• Compiler: C++11 support required (gcc-4.6.3+, Visual Studio 2015, or clang-3.3+).
• Build Tool: make.
• Library: Boost must be installed. You must specify the Boost path in the Makefile.

To install Boost (example):

$wget https://dl.bintray.com/boostorg/release/1.63.0/source/boost_1_63_0.zip
$unzip boost_1_63_0.zip
$sudo mv boost_1_63_0 /usr/local/bin

Build Instructions

Mac OS or Linux

git clone https://github.com/facebookresearch/Starspace.git
cd Starspace
make

Windows

Open the following solution in Visual Studio: MVS\StarSpace.sln

Python Wrapper

Refer to the README located in the python/ directory for building the Python wrapper.

StarSpace can read from compressed gzip files to handle large datasets.

1. Build with compression support: Instead of the standard make, use:

   make -f makefile_compress

2. Prepare data: Split your input file into chunks and compress them (e.g., input00.gz, input01.gz, etc.):

   split -d -l xxx original_input.txt input && gzip input*

3. Run training: Specify the -compressFile gzip and -numGzFile arguments:

   ./starspace -trainFile input -compressFile gzip -numGzFile 10 ...

Use PageSpace to learn embeddings for recommending items (like pages, movies, or restaurants) to users based on their historical interactions (like fanning a page or watching a movie).

In this model, users are represented as a 'bag of pages' they follow. Instead of learning direct user embeddings, a user's embedding is calculated as the average embedding of the pages they follow. This allows the model to generalize to new users without retraining.

Input Format: Each line represents a user, containing a space-separated list of pages: page_1 page_2 ... page_M

Training Logic: Set -trainMode 1. At each training step, one random page from the bag is selected as the label, and the remaining pages are used as input.

./starspace train -trainFile input.txt -model pagespace -label 'page' -trainMode 1

To inspect the quality of a trained model by typing an input and seeing predicted labels, build and run the query_predict utility.

Usage:

1. Build: make query_predict
2. Run: ./query_predict <model> k [basedocs]

• <model>: The trained StarSpace model.
• k: Number of top predictions to show (ranked first).
• [basedocs]: Optional file of documents to rank. If omitted, labels in the dictionary are used.

To find the nearest entities in embedding space for a given input, build and run the query_nn utility.

Usage:

1. Build: make query_nn
2. Run: ./query_nn <model> [k]

• <model>: The trained StarSpace model.
• [k]: Optional number of nearest neighbors to search for (default: 5).

If you have trained a model with trainMode=0, you can use the predictTags method to retrieve tag predictions for a given input string.

To use this, you must first initialize the model using initFromSavedModel and the corresponding TSV data using initFromTsv. The predictTags method returns a dictionary where keys are tags and values are probabilities.