README.md

Examples

We host a number of example scripts for various customization of STORM (e.g., use your favorite language models, use your own corpus, etc.). These examples can be starting points for your own customizations and you are welcome to contribute your own examples by submitting a pull request to this directory.

Run STORM with your own language model

run_storm_wiki_gpt.py provides an example of running STORM with GPT models, and run_storm_wiki_claude.py provides an example of running STORM with Claude models. Besides using close-source models, you can also run STORM with models with open weights.

run_storm_wiki_mistral.py provides an example of running STORM with Mistral-7B-Instruct-v0.2 using VLLM server:

1. Set up a VLLM server with the Mistral-7B-Instruct-v0.2 model running.

2. Run the following command under the root directory of the repository:

    python examples/storm_examples/run_storm_wiki_mistral.py \
       --url $URL \
       --port $PORT \
       --output-dir $OUTPUT_DIR \
       --retriever you \
       --do-research \
       --do-generate-outline \
       --do-generate-article \
       --do-polish-article
   

   • --url URL of the VLLM server.
   • --port Port of the VLLM server.

Besides VLLM server, STORM is also compatible with TGI server or Together.ai endpoint.

Run STORM with your own corpus

By default, STORM is grounded on the Internet using the search engine, but it can also be grounded on your own corpus using VectorRM. run_storm_wiki_with_gpt_with_VectorRM.py provides an example of running STORM grounding on your provided data.

1. Set up API keys.

   • Make sure you have set up the OpenAI API key.
   • VectorRM use Qdrant to create a vector store. If you want to set up this vector store online on a Qdrant cloud server, you need to set up QDRANT_API_KEY in secrets.toml as well; if you want to save the vector store locally, make sure you provide a location for the vector store.

2. Prepare your corpus. The documents should be provided as a single CSV file with the following format:

   content	title	url	description
   I am a document.	Document 1	docu-n-112	A self-explanatory document.
   I am another document.	Document 2	docu-l-13	Another self-explanatory document.
   ...	...	...	...

   • url will be used as a unique identifier of the document in STORM engine, so ensure different documents have different urls.
   • The contents for title and description columns are optional. If not provided, the script will use default empty values.
   • The content column is crucial and should be provided for each document.

3. Run the command under the root directory of the repository: To create the vector store offline, run

   python examples/storm_examples/run_storm_wiki_gpt_with_VectorRM.py \
       --output-dir $OUTPUT_DIR \
       --vector-db-mode offline \
       --offline-vector-db-dir $OFFLINE_VECTOR_DB_DIR \
       --csv-file-path $CSV_FILE_PATH \ 
       --device $DEVICE_FOR_EMBEDDING(mps, cuda, cpu) \
       --do-research \
       --do-generate-outline \
       --do-generate-article \
       --do-polish-article
   

   To create the vector store online on a Qdrant server, run

   python examples/storm_examples/run_storm_wiki_gpt_with_VectorRM.py \
       --output-dir $OUTPUT_DIR \
       --vector-db-mode online \
       --online-vector-db-url $ONLINE_VECTOR_DB_URL \
       --csv-file-path $CSV_FILE_PATH \
       --device $DEVICE_FOR_EMBEDDING(mps, cuda, cpu) \
       --do-research \
       --do-generate-outline \
       --do-generate-article \
       --do-polish-article
   

4. Quick test with Kaggle arXiv Paper Abstracts dataset:

   • Download arxiv_data_210930-054931.csv from here.

   • Run the following command under the root directory to downsample the dataset by filtering papers with terms [cs.CV] and get a csv file that match the format mentioned above.

     python examples/storm_examples/helper/process_kaggle_arxiv_abstract_dataset.py --input-path $PATH_TO_THE_DOWNLOADED_FILE --output-path $PATH_TO_THE_PROCESSED_CSV
     

   • Run the following command to run STORM grounding on the processed dataset. You can input a topic related to computer vision (e.g., "The progress of multimodal models in computer vision") to see the generated article. (Note that the generated article may not include enough details since the quick test only use the abstracts of arxiv papers.)

     python examples/storm_examples/run_storm_wiki_gpt_with_VectorRM.py \
         --output-dir $OUTPUT_DIR \
         --vector-db-mode offline \
         --offline-vector-db-dir $OFFLINE_VECTOR_DB_DIR \
         --csv-file-path $PATH_TO_THE_PROCESSED_CSV \
         --device $DEVICE_FOR_EMBEDDING(mps, cuda, cpu) \
         --do-research \
         --do-generate-outline \
         --do-generate-article \
         --do-polish-article
     

   • For a quicker run, you can also download the pre-embedded vector store directly from here.

     python examples/storm_examples/run_storm_wiki_gpt_with_VectorRM.py \
         --output-dir $OUTPUT_DIR \
         --vector-db-mode offline \
         --offline-vector-db-dir $DOWNLOADED_VECTOR_DB_DR \
         --do-research \
         --do-generate-outline \
         --do-generate-article \
         --do-polish-article