Spaces:
Runtime error
Runtime error
| title: Skops Model Card Creator | |
| emoji: 🐨 | |
| colorFrom: indigo | |
| colorTo: blue | |
| sdk: streamlit | |
| sdk_version: 1.17.0 | |
| app_file: app.py | |
| pinned: false | |
| license: bsd-3-clause | |
| tags: | |
| - sklearn | |
| - skops | |
| - model card | |
| # Create a Hugging Face model repository for scikit learn models | |
| This page aims to provide a simple interface to use the | |
| [`skops`](https://skops.readthedocs.io/) model card and HF Hub creation | |
| utilities. | |
| Below, we will explain the steps involved to create your own model repository to | |
| host your scikit-learn model: | |
| 1. Prepare the model repository | |
| 2. Edit the model card | |
| 3. Create the model repository on Hugging Face Hub | |
| ## Step 1: Prepare the model repository | |
| In this step, you do the necessary preparation work to create a [model | |
| repository on Hugging Face Hub](https://huggingface.co/docs/hub/models). | |
| ### Upload a model | |
| Here you should upload the sklearn model we want to present in the model | |
| repository. The model should be stored either as a ``pickle`` file or it should | |
| use the [secure skops persistence | |
| format](https://skops.readthedocs.io/en/stable/persistence.html). Later, this | |
| model will be uploaded to the model repository so that you can share it with | |
| others. | |
| The uploaded model should be a scikit-learn model or a model that is compatible | |
| with the sklearn API, e.g. using [XGBoost sklearn | |
| wrapper](https://xgboost.readthedocs.io/en/stable/python/python_api.html#module-xgboost.sklearn) | |
| when it's an XGBoost model. | |
| If you just want to test out the application and don't want to upload a model, a | |
| dummy model will be used instead. | |
| ### Upload input data | |
| It's possible to upload input data as a csv file. If that is done, the first few | |
| rows of the input data will be used as sample data for the model, e.g. when | |
| trying out the [inference API](https://huggingface.co/inference-api). | |
| ### Choose the task type | |
| Choose the type of task that the model is intended to solve. It can be either | |
| classification or regression, with input data being either tabular in nature or | |
| text. | |
| ### Requirements | |
| This is the list of Python requirements needed to run the model. | |
| ### Choose the model card template | |
| This is the final step and choosing one of the options will bring you to the | |
| editing step. | |
| #### Create a new skops model card | |
| This is the recommended way of getting started. The skops model card template | |
| prefills the model card with some [useful | |
| contents](https://skops.readthedocs.io/en/stable/model_card.html#model-card-content) | |
| that you probably want to have in most model cards. Don't worry: If you don't | |
| like part of the content, you can always edit or delete it later. | |
| #### Create a new empty model card | |
| If you want to start the model card completely from scratch, that's also | |
| possible by choosing this option. It will generate a completely empty model card | |
| for you that you can fashion to your liking. | |
| #### Load existing model card from HF Hub | |
| If you want to use an existing model card and edit it, that's also possible. | |
| Please enter the Hugging Face Hub repository ID here and the corresponding model | |
| card will be loaded. The repo ID is typically someting like `username/reponame`, | |
| e.g. `openai/whisper-small`. Some models also omit the user name, e.g. `gpt2`. | |
| Note that when you choose an existing model card, a couple of files will be | |
| downloaded, because they may be required to render the model card (e.g. images). | |
| Therefore, depending on the repository, this step may take a bit. | |
| If you notice any problems when rendering the existing model card, please let us | |
| know by [creating an issue](https://github.com/skops-dev/skops/issues). | |
| ## Step 2: Edit the model card | |
| Before creating the model repository, it is crucial to ensure that the [model | |
| card](https://huggingface.co/blog/model-cards) is edited to best represent the | |
| model you're working on. This can be achieved in the editing step, which is | |
| described in more detail below. | |
| ### Editing sidbar | |
| In the left sidebar, you will be able to edit the model card, whereas the main | |
| screen is reserved for rendering the model card so that you see what you will | |
| get. We will start by describing the editing sidebar. | |
| Tip: You should increase the width of the side bar if it is too narrow for your | |
| taste. | |
| #### Undo, redo & reset | |
| On top of the side bar, you have the option to undo, redo, and reset the last | |
| operation you did. Say, you accidentally made a change, just press the `Undo` | |
| button to undo this change. Similarly, if you want to undo your undo operation, | |
| press the `Redo` button. Finally, if you press `Reset`, all your operations will | |
| be undone (but don't worry if you click the button accidentally, you can redo | |
| all of them if you want). | |
| #### Save, create repo & delete | |
| These buttons are intended for when you finished editing the model card. When | |
| you click on `Save`, you will get the option to download the model card as a | |
| markdown file. | |
| When clicking the `Create Repo` button, you will be taken to the next screen, | |
| which offers you to create a model repository on Hugging Face Hub. This step | |
| will be explained in more detail further below. | |
| Finally, you can click on `Delete` to completely discard all the changes you | |
| made and be taken back to the start screen of the app. Be careful, any change | |
| you made will be lost. It is thus advised to first save the model card before | |
| pressing `Delete`. | |
| #### Edit a section | |
| Each section has its own form field, which allows you to make edits. Change the | |
| name of the section or change the content (or both), then click `Update` to see | |
| a preview of your change. As with all other operations, you can undo the change | |
| by clicking on `Undo`. | |
| #### Delete a section | |
| Below the form field for editing the section, you will find a `Delete` button | |
| (including the name of the section to make it clear which section it refers to). | |
| If you click that button, the whole section, _including its subsections_, will | |
| be deleted. Again, click on `Undo` if you accidentally deleted something that | |
| you want to keep. | |
| #### Add section below | |
| If you click on this button, a new subsection wil be created under the current | |
| section. This will create a section with a dummy title and dummy content, which | |
| you can then edit. | |
| Note that this will create a new _subsection_. If there are already existing | |
| subsections in the current section, the new subsection will be created _below_ | |
| those existing subsections. So the new subsection you create might not appear | |
| exactly where you expect it to appear. To illustrate this, assume that we have | |
| the following sections and subsections: | |
| - Section A | |
| - Subsection A.1 | |
| - Subsection A.2 | |
| - Section B | |
| If you create a new section below "Section A", it will be created on the same | |
| level, and below of, "Subsection A.2", resulting in the following structure: | |
| - Section A | |
| - Subsection A.1 | |
| - Subsection A.2 | |
| - NEW SUBSECTION | |
| - Section B | |
| If you create a new section below the "Subsection A.1", you will actually create | |
| a sub-subsection, resulting in the following structure instead: | |
| - Section A | |
| - Subsection A.1 | |
| - NEW SUB-SUBSECTION | |
| - Subsection A.2 | |
| - Section B | |
| Hopefully, this clarifies things. Unfortunately, there is no possibility (yet) | |
| to re-order sections. | |
| #### Add figure below | |
| This button works quite similarly to adding a new section. The main difference | |
| is that instead of having a text area to enter content, you will be asked to | |
| upload an image file. By default, a dummy image will be shown in the preview. | |
| #### Add metrics (only skops template) | |
| If you have chosen the skops template, you will see an additional field called | |
| `Add metrics` near the top of the side bar. Here you can choose metrics you want | |
| to be shown in the model card, e.g. the accuracy the model achieved on a | |
| specific dataset. Please enter one metric per line, with the metric name on the | |
| left, then an `=` sign, and the value on the right, e.g. `accuracy on test set = | |
| 0.85`. | |
| After pressing `update`, the metrics will be shown in a table in the section | |
| `Model description/Evaluation Results`. You can always add or remove metrics | |
| from this field later. If you want to delete this section completely, look for | |
| its edit form further below and press `Delete`. There, you can also edit the | |
| table in a more fine grained way, e.g. by changing the alignment. | |
| If you don't use the skops template and still want to add a table, it is | |
| possible to do that, but it's requires a bit more work. Add a new section as | |
| described above, then, in the text area, create a table using the [markdown | |
| table | |
| syntax](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables#creating-a-table). | |
| ### Model card visualization | |
| The main part of the page will show you what the final model card will look | |
| like. | |
| #### Metadata | |
| On the very top, you can see the metadata of the model card (it is collapsed by | |
| default). The metadata can be very useful for features on the HF Hub, e.g. | |
| allowing other users to find your model by a given tag. | |
| Right now, it is not possible to edit the metadata directly from here. But don't | |
| worry, once you have created the model card repository, you can easily edit the | |
| metadata there. | |
| #### Table of Contents | |
| For your convenience, a table of contents is also shown at the top (collapsed by | |
| default). This is useful if you have a bigger model card and want to see the | |
| overview of all its contents. | |
| #### Markdown preview | |
| Finally, the model card itself is shown. This is how the model card will look | |
| like once it is saved as markdown and then rendered. | |
| ## Step 3: Creating a model repository | |
| After you have finished editing the model card, it is time to create a model | |
| repository on Hugging Face Hub. Click on `Create Repo` and you will be taken to | |
| the final step of the process. | |
| ### Back & Delete | |
| If you find yourself wanting to make more edits to the model card, just click on | |
| the `Back` button and you'll be brought back to the editing step. | |
| You can also click `Delete`, which will discard all your changes and bring you | |
| back to the start page. Be careful: This step cannot be undone and all your | |
| progress will be lost. | |
| ### Files included in the repository | |
| For your convenience, this will show a preview of all the files included in the | |
| repository, as well as their sizes. Don't create a repository if you see files | |
| there that you don't want to be uploaded. | |
| ### Privacy settings | |
| By default, a private repository will be created. If you untick this box, it | |
| will be public instead. More information on what that implies can be found in | |
| the [docs on repository | |
| settings](https://huggingface.co/docs/hub/repositories-settings). | |
| ### Name of the repository | |
| Here you have to enter the name of the repository. Typically, that's something | |
| like `username/reponame` or `organame/reponame`. This field is mandatory and you | |
| should ensure that the corresponding repository ID does not exist yet. | |
| ### Enter your Hugging Face token | |
| Here you need to paste your Hugging Face token, which is used for | |
| authentication. The token can be found [here](https://hf.co/settings/token) and | |
| it always starts with "hf_". Entering a token is necessary to create a | |
| repository. | |
| Note that if you don't already have an account on Hugging Face, you need to | |
| create one to get a token. It's free. | |
| ### Create a new repository | |
| Once all the required fields are filled, click on this button to create the | |
| repository. Depending on the size, it may take a couple of seconds to finish. | |
| Once it is created, you will see a success notification that includes the link | |
| to the repository. Congratulations, you're done! | |
| ## Troubleshooting | |
| ### Not all skops features available | |
| This app is based on the [skops model card | |
| feature](https://skops.readthedocs.io/en/stable/model_card.html#model-card-content). | |
| However, it does not support all the options that are available there. If you | |
| want to use all those options in a programmatic fashion, please follow the link | |
| and read up on what it takes to create a model card with skops. The full power | |
| of the `Card` class is documented | |
| [here](https://skops.readthedocs.io/en/stable/modules/classes.html#skops.card.Card). | |
| ### Strange behavior | |
| If the app behaves strangely, shows error messages, or renders incorrectly, it | |
| may be necessary to refresh the browser tab. This will take you back to the | |
| start page, with all progress being lost. If you can reproduce that behavior, | |
| please [creating an issue](https://github.com/skops-dev/skops/issues) and let us | |
| know. | |
| ### Contact | |
| If you want to contact us, you can join our discord channel. To do that, follow | |
| [these | |
| instructions](https://skops.readthedocs.io/en/stable/community.html#discord). | |