\section{Requesting additional disk space}\label{sec:disk_flow}

Hugging Face Spaces allow users to choose from a variety of backend options,\footnote{\url{https://hf.co/docs/hub/spaces-overview\#hardware-resources}} with basic, free variants and more powerful paid alternatives. Academic users are encouraged to apply for community grants which can result in granting access to free, upgraded backend machines.\footnote{\url{https://hf.co/docs/hub/spaces-gpus}} In order to apply, one can navigate to the \texttt{Settings} tab in their Space and click on the \texttt{Apply for a community GPU grant} highlighted text. As demonstrated in Figure~\ref{fig:disk_request}, this will open a pop-up window where users can describe their use cases and backend demands. The applications are evaluated on a case-by-case basis. Given that Spaces are primarily intended for hosting Machine Learning demos, GPU provisioning takes the front seat; however, readers are welcome to submit their disk space requests via the same flow.

\begin{figure}
\centering
\includegraphics[width=\columnwidth]{figures/disk_request_flow.pdf}
\caption{Additional disk space request flow.}
\label{fig:disk_request}
\end{figure}


\section{Introduction}
\label{sec:intro}

The commodification of data has had a transformative effect on science in general~\citep{hey2009-fourth-paradigm} and machine learning in particular~\citep{mitchell-measuring-data-22}. The race to train ever-larger language models is so contingent upon having access to immeasurable quantities of text~\citep{chinchilla-hoffmann-22} that datasets have become---as~\citet{bender-gebru-stochastic-21} contend---``too large to document'' both technically~\citep{bender-gebru-stochastic-21} and methodologically~\citep{jo-archives-20}. This often leads to a ``train first, ask questions later'' approach to model training~\citep{akiki-bigscience-22}, itself a concrete instance of convenience experimentation~\citep{krohs-convenience-experimentation}, an approach to research that is modulated by the availability of a resource and ease of a method, rather than the suitability thereof to the problem at hand. In this sense, \citet{beaulieu-leonelli-2021-data} deem it important to differentiate between the availability of data and its suitability, especially in light of the misconception that Web data is representative of all human experiences and immune to the ever-widening \emph{digital divide}~\citep{leonelli-science-big-data}. They point out that the divide not only exists but actively limits this representativeness---both socio-economic and socio-cultural---of the Web, which in turn reinforces biases of the artifacts that leverage it~\citep{bender-gebru-stochastic-21}.

Being unable to easily audit large datasets incentivizes researchers to release models trained on data they do not truly understand~\citep{mitchell-measuring-data-22} leading to model behaviors that are hard to study, predict or trace~\citep{mitchell-measuring-data-22,hooker-archaelogy-22,akyurek-etal-2022-towards}. This is especially problematic in light of the potential real-world harms that ensue~\citep{llm-risks-harms,hutchinson-etal-2020-social,twitter-abusive-behavior-crowdsourcing,bias-online-fiction-writing}. Being able to properly understand the limitations of our datasets is a necessary first step toward understanding the harmful biases and failure modes of the artifacts that build upon them. Understanding the training data is therefore a critical step in the process of auditing large language models~\citep{auditing-llms}.
\enlargethispage{3\baselineskip}

It is from this vantage point that we initially developed ~Spacerini\xspace as an open-source tool for the quick indexing and deployment of shareable search engines, but have also since come to realize its potential in being useful for an even wider audience interested in making their text artifacts searchable. This includes IR students, Digital Humanists, Shared Tasks organizers, and digital investigative journalists. We cover these use cases in more detail in Section~\ref{sec:use-cases}. ~Spacerini\xspace was designed as a modular framework that facilitates the indexing, creation, and free hosting of graphical search interfaces for text datasets. It helps streamline the process of auditing large datasets by allowing users to effortlessly index their text collections and deploy them as as search systems that can be accessed by anyone. It does so by standing on the shoulders of battle-tested open-source libraries from the Castorini~\citep{Lin_etal_SIGIR2021_Pyserini} and Hugging Face~\citep{abid-2019-gradio,huggingface-datasets-lhoest-21} ecosystems and enhancing the interoperability between them to enable quick indexing and free deployment of search interfaces.

The key advantage of ~Spacerini\xspace is its ability to simplify the search process and retrieve relevant data points from massive datasets with ease, allowing researchers to conduct quick and efficient audits, while abstracting away all the minutiae of indexing data or hosting services. We believe that this provides an opportunity for collaboration and transparency in IR and NLP research. With the creation and sharing of search indexes publicly, practitioners, researchers and the general public can work together to pinpoint problematic content, find duplicates, and identify biases in datasets. Specific to the IR community, Spacerini allows a convenient and universal approach to index sharing, which greatly facilitates the demonstration of retrieval systems and the reproduction from other researcher teams.

\section{Background}

Large scale, predominantly web-mined text datasets have been proliferating in NLP recently, giving rise to publications~\cite{laurencon2022the, gao-pile-21,suarez-processing-huge-corpora,t5-raffel} which often contain interesting analyses of the specific datasets being presented, however, usually lack any comparison to existing resources beyond basic metrics such as sizes of the datasets or languages they contain. 

As discussed in Section~\ref{sec:intro}, in the face of an increased scrutiny of the models trained on datasets in question, the topic of data understanding and governance has been gaining more traction, being accepted as an important part of research. Efforts such as those of~\citet{mitchell-measuring-data-22} contribute frameworks for more standardised and reproducible metrics and measurements of datasets, and we position ourselves as a complementary continuation of their work, focusing on a more curatorial and qualitative assessment that might not readily fit under the umbrella of ``measurements''. We therefore aim to fill the gap in the evaluation landscape by facilitating qualitative, rather than quantitative analysis of large scale data collections.

Similarly to the authors of Gradio~\cite{abid-2019-gradio}, a Python package for fast development of Machine Learning demos, we believe that the accessibility of data and model analysis tools is crucial to building both the understanding of and the trust in the underlying resources.
The potential of relevance-based interfaces to massive textual corpora, the creation of which can be facilitated by leveraging  toolkits such as Pyserini~\cite{Lin_etal_SIGIR2021_Pyserini},
 has previously been tapped into by the researchers at the Allen Institute of AI who propose a C4~\cite{t5-raffel} search engine\footnote{\url{https://c4-search.apps.allenai.org/}}. 
 Similar interfaces have also been found useful in more specialised domains, e.g. in COVID-related datasets~\citep{zhang2020covidex}, news quotes~\cite{Vukovi__2022}, or medical literature~\citep{cancer-nlp-no-code}. However, while these solutions are undeniably useful, they remain very contextual: dataset-specific, and project-specific. We believe ~Spacerini\xspace to be the first generalizable tool which proposes an end-to-end pipeline automating the route from raw text to qualitative analysis.



\section{Spacerini}
~Spacerini\xspace is a modular framework that integrates Pyserini with the Hugging Face ecosystem to streamline the process of going from any Hugging Face text dataset---either local or hosted on the Hugging Face Hub---to a search interface driven by a Pyserini index that can be deployed for free on the Hugging Face Hub.

In what follows, we deconstruct an example script\footnote{\href{https://github.com/castorini/hf-spacerini/blob/main/examples/scripts/gradio-demo.py}{gradio-demo.py}} to showcase the different features enabled by ~Spacerini\xspace. When run end-to-end, the script pulls a dataset from the Hugging Face hub, pre-processes it, indexes it, creates a gradio-based search interface and pushes that to the Web as a Hugging Face Spaces demo. This is only meant as a feature-complete demo, and we don't expect most people to want to integrate every step into their workflows, but rather to cherry-pick and decide what best to use depending on context.

\begin{figure}[!ht]
    \centering
    \includegraphics[width=\columnwidth,natwidth=5016px,natheight=2672px]{figures/spacerini_xsum_screenshot.eps}
    \caption{
    Search interface for the Extreme Summarization (xsum) dataset deployed on Hugging Face \texttt{Spaces} using ~Spacerini\xspace.
    }
    \label{fig:search_screenshot}
\end{figure}

\subsection{Loading Data}
All our workflows are backed by the Hugging Face \texttt{datasets} library~\citep{huggingface-datasets-lhoest-21}, itself based on the extremely efficient Apache Arrow format. \texttt{Datasets} is a mature library which provides a standardized interface to any tabular dataset, in particular, to tens of thousands of community datasets hosted on the Hugging Face Hub\footnote{\url{https://hf.co/datasets}}. The \texttt{datasets} library gives fine-grained control over the lifecycle of tabular datasets, which we choose to abstract away through a set of opinionated data loading functions that cover the use cases we deem relevant to information retrieval. We also add new functionality, such as the ability to load any document dataset from the \texttt{ir\_datasets} library using for example the following one-liner to load MS~MARCO as a Hugging Face \texttt{datasets.Dataset} object using a function from the \texttt{data} subpackage:


\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.data import load_ir_dataset
hf_dset = load_ir_dataset("msmarco-passage")
\end{minted}
We include wrappers to load database tables, pandas DataFrames~\citep{pandas-software,pandas-paper}, and text datasets on disk, as well as the ability to load any dataset either in memory-mapped mode or in streaming mode: the former makes it possible to handle larger-than-memory datasets, and the latter larger-than-disk datasets that can be streamed from a remote location such as the Hugging Face Hub.

\subsection{Pre-processing}
~Spacerini\xspace also provices a \texttt{preprocess} subpackage which offers a range of customizable pre-processing options for preparing datasets.
This module includes a sharding utility that enables the partitioning of large datasets into smaller, more manageable chunks for efficient parallel processing.
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.preprocesss import shard_dataset
shard_dataset(
    hf_dataset=hf_dset,               
    shard_size="1GB",
    column_to_index="text", 
    shards_paths="msmarco-shards",
)
\end{minted}
\subsection{Indexing}
~Spacerini\xspace's \texttt{index} subpackage leverages Pyserini to provide very efficient Lucene indexing and allow users to easily and quickly index large datasets, either sharded in the pre-processing step, or any text format accepted by Pyserini, and streaming text datasets, such as those returned by ~Spacerini\xspace's \texttt{data} subpackage. This subpackage also exposes several tokenization options using existing language-specific analyzers~\footnote{\url{https://lucene.apache.org/core/9_5_0/analysis/common/index.html}} as well as Hugging Face subword tokenizers~\citep{moi-hf-tokenizers}.
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.index import index_json_shards
index_json_shards(
    shards_path="msmarco-shards",
    index_path="app/index",
)
\end{minted}
\subsection{Template-based Search Interfaces}
Having indexed a collection, one can easily spin up a frontend using the \texttt{frontend} subpackage and one of many provided templates\footnote{\url{https://github.com/castorini/hf-spacerini/tree/main/templates}}. These are built using \texttt{cookiecutter},\footnote{\url{https://github.com/cookiecutter/cookiecutter}} a Python templating library for software projects. We provide a few batteries-included frontend templates based both the Gradio\footnote{\url{https://gradio.app/}} and Streamlit \footnote{\url{https://streamlit.io/}} demo app frameworks, both of which are natively supported by Hugging Face \texttt{Spaces}. Figure~\ref{fig:search_screenshot} showcases a search engine built using one of our Streamlit templates.
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.frontend import create_app
cookiecutter_vars = {"dset_text_field": "text,
                "metadata_field": "docid",
                "space_title": "MS MARCO Search",
                "local_app": "app"}
create_app(
    template="gradio-vanilla",
    extra_context_dict=cookiecutter_vars,
    output_dir=".",
)
\end{minted}
\subsection{Deployment to Hugging Face Spaces}
The local apps developed in the previous subsection can then be pushed to Hugging Face Spaces and hosted there for free. One can then further customize the running app from the browser, for example to add functionality not provided by the chosen template.
\enlargethispage{1\baselineskip}
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.frontend import create_space_from_local
create_space_from_local(
    space_slug="msmarco-passage-search,
    organization="spacerini,
    space_sdk="gradio",
    local_dir=LOCAL_APP,
    delete_after_push=True,
)
\end{minted}
\subsection{Sharing Indexes as Hugging Face Datasets}\label{sec:index-sharing}
Orthogonal to the workflow presented so far, is the ability to upload Lucene indexes to the Hugging Face Hub using shareable dataset repositories and enabling reproducible retrieval experiments.
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.index import push_index_to_hub

push_index_to_hub(
    dataset_slug="lucene-english-analyzer-msmarco",
    index_path="index",
)
\end{minted}
Any index can then just as easily be downloaded for local use:
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.index import load_index_from_hub

index_path = load_index_from_hub("lucene-fr-analyzer-")
\end{minted}

\subsection{Search and Pagination}
Search features are provided by the \texttt{search} subpackage and leverage the memory-mapping feature of Arrow tables to load the entire table of results---no matter how big---only materializing the specific shard that corresponds to the requested result page.
\begin{minted}
[
frame=lines,
framesep=2mm,
baselinestretch=1.2,
bgcolor=LightGray,
fontsize=\footnotesize,
]
{python}
from spacerini.search import result_indices, result_page 

ix = result_indices(
    "Lorem Ipsum",
    num_results=1_000,
    INDEX_PATH,
)

last_results_page = result_page(
    hf_dset,
    ix,
    page=-1,
    results_per_page=20,
).to_pandas()    
\end{minted}


\section{Use Cases and Examples}
\label{sec:use-cases}

~Spacerini\xspace is designed to enable qualitative analysis of large-scale textual corpora without the need for extensive engineering work. The tool can be used in dataset auditing campaigns, such as those carried out by~\citet{kreutzer-etal-2022-quality} or in data annotation efforts. It may be applied to inspect failures of large scale language model predictions and find potential sources of memorized generations. AI Ethics researchers can employ the tool to find evidence supporting their hypotheses about the content of the models' training datasets. 

\enlargethispage{1\baselineskip}

Given its tight integration with Pyserini, ~Spacerini\xspace can also be leveraged by IR researchers to experiment with modifications of their retrieval pipelines in user studies (e.g. by exposing retrieval options such as BM25 and RM3 parameters in the the user interface) or to deploy demos of their working prototypes. Reproducibility for IR experiments is further enhanced thanks to the index sharing abilities introduced in Section~\ref{sec:index-sharing}.

~Spacerini\xspace can also be leveraged by Digital Humanists, Archivists and Librarians looking to index their collections. Indeed, GLAM~(Galleries, libraries, archives, and museums) collections are increasingly being made available as datasets. Furthermore, there is a growing interest in the digital humanities in training and using languages models, as demonstrated by the success of projects such as the \emph{BERT for Humanists Project}\footnote{https://www.bertforhumanists.org/}. This makes it especially pressing to have easy access ways to critically examine the data that goes into such models. In the context of the digital and computational humanities, indexing data relevant to these efforts is often not an easy task, and often project-based and contingent upon precarious funding arrangements. Having a project-agnostic tool like ~Spacerini\xspace could prove valuable to this community and a useful addition to toolkits such as the GLAM Workbench~\citep{glam-workbench}.

Given its low engineering barrier of entry, ~Spacerini\xspace can be a good addition to IR courses with a practical component, where students are tasked with developing search engines, by providing an easy-to-deploy interface for their developed retrieval systems.

~Spacerini\xspace can also be leveraged by organizers of shared tasks such as MIRACL~\cite{zhang-miracl-22} and Touch\'{e}~\citep{touche-22}, who want to help participants explore the datasets without forcing them to download large volumes of data. It can also be used as a platform for participants to deploy working prototypes with a unified interface.

~Spacerini\xspace can help data journalists and digital investigative journalists index, explore, and understand open data, in a similar vein to the functionality provided by the Aleph suite.\footnote{\url{https://docs.alephdata.org/}} Providing technical tools to data journalists is a crucial in uncovering matters of public interest, as was evident by role played by the collaborative use of the Neo4j graph database in unraveling the corrupt network surrounding tax havens~\citep{neo4j-panama}.

Finally, three features of Hugging Face Spaces make them especially attractive for users: (1)~~they can leverage private datasets, meaning that one can provide search access to a dataset without sharing the underlying data,(2)~~they can be seamlessly embedded into HTML, specifically Gradio-based Spaces which can be embedded as \emph{Web Components}\footnote{\url{https://developer.mozilla.org/en-US/docs/Web/Web_Components}} so that users can easily integrate a ~Spacerini\xspace-based search feature into their own sites\footnote{For example: \url{https://cakiki.github.io/search-engine/}}, and (3)~~Gradio-based Spaces expose a FastAPI\footnote{\url{https://github.com/tiangolo/fastapi}} endpoint that can be queried to access the functionality of the space, making deployed search engines accessible through HTTP~calls.

\section{Limitations and Future Plans}
The main limitation of the off-the-shelf variant of ~Spacerini\xspace is the disk space limit imposed by Hugging Face Spaces, which is currently set to 50~GB.\footnote{\url{https://huggingface.co/docs/hub/spaces-overview\#hardware-resources}} 
While not enough to accommodate entire corpora such as ROOTS or The Pile, such large datasets are most often amalgamations of constitutents datasets which can each be studied independently. This limit has no bearing on ~Spacerini\xspace search apps deployed locally. Should users still want to get more disk space for their Spaces-hosted indexes, they are welcome to apply for community grants offered by Hugging Face.

Planned improvements to the library include automating the creation of dataset cards (Or rather ``index cards'') when pushing an index to the Hugging Face Hub, more support for dense indexing features provided by Pyserini, as well as more fine-grained support of document tokenization. We also look forward to community contributions both to the codebase and to the frontend templates.


\section{Conclusion}

We presented ~Spacerini\xspace, a modular framework that enables the quick and free deployment and serving of template-based search indexes as interactive applications. The need for such a tool is especially pressing as large language models have come to consume inordinate amounts of text data, reinforcing the need for a qualitative exploration and understanding of datasets to assess them in a way that is impenetrable to quantitative analyses alone.

~Spacerini\xspace leverages features from both the \texttt{Pyserini} toolkit and the Hugging Face ecosystem to facilitate the creation and hosting of user-friendly search systems for text datasets. Users can easily index their collections and deploy them as ad-hoc search interfaces, making the retrieval of relevant data points a quick and efficient process. The user-friendly interface enables non-technical users to effectively search massive datasets, making ~Spacerini\xspace a valuable tool for anyone looking to audit their text collections qualitatively. The framework is open-source and available on GitHub: \url{https://github.com/castorini/hf-spacerini}.

Finally, we emphasize that ~Spacerini\xspace is a first step in the direction of systematic dataset auditing, and more work is still needed to create standardized structures that leverage tools such as ~Spacerini\xspace to properly document the different axes of interest that are appropriate for a given usage context.

\section*{Acknowledgments}
We are grateful to Daniel van Strien, Yuvraj Sharma, Omar Sanseviero, Julien Chaumond, Lucain Pouget, Abubakar Abid, and Leandro von Werra for their tireless support and invaluable advice throughout this project.