From c6d2714c520f3e27051bbc0468bd79a2dc62837b Mon Sep 17 00:00:00 2001
From: Krrish Dholakia <krrishdholakia@gmail.com>
Date: Wed, 12 Nov 2025 13:42:55 -0800
Subject: [PATCH] docs(model_access_guide.md): document how model access works
 on litellm

---
 .../docs/projects/{Softgen => Softgen.md}     |  0
 .../docs/proxy/model_access_guide.md          | 77 +++++++++++++++++++
 docs/my-website/sidebars.js                   |  2 +-
 3 files changed, 78 insertions(+), 1 deletion(-)
 rename docs/my-website/docs/projects/{Softgen => Softgen.md} (100%)
 create mode 100644 docs/my-website/docs/proxy/model_access_guide.md

diff --git a/docs/my-website/docs/projects/Softgen b/docs/my-website/docs/projects/Softgen.md
similarity index 100%
rename from docs/my-website/docs/projects/Softgen
rename to docs/my-website/docs/projects/Softgen.md
diff --git a/docs/my-website/docs/proxy/model_access_guide.md b/docs/my-website/docs/proxy/model_access_guide.md
new file mode 100644
index 0000000000..1c4e5a56be
--- /dev/null
+++ b/docs/my-website/docs/proxy/model_access_guide.md
@@ -0,0 +1,77 @@
+# How Model Access Works
+
+## Concept 
+
+Each model onboarded is a "model deployment" in LiteLLM. 
+
+These model deployments are assigned to a "model group", via the "model_name" field in the config.yaml. 
+
+## Example
+
+```yaml
+model_list:
+  - model_name: my-custom-model
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+```
+
+In here, we onboard a model deployment for the model `gpt-4o` and assign it to the model group `my-custom-model`.
+
+
+## Access Control
+When you give access to a key/user/team, you are giving them access to a "model group". 
+
+Example:
+
+```bash
+curl --location 'http://localhost:4000/key/generate' \
+--header 'Authorization: Bearer <your-master-key>' \
+--header 'Content-Type: application/json' \
+--data-raw '{"models": ["my-custom-model"]}'
+```
+
+## Loadbalancing 
+
+You can add multiple model deployments to a single "model group". LiteLLM will automatically load balance requests across the model deployments in the group.
+
+Example:
+
+```yaml
+model_list:
+  - model_name: my-custom-model
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+  - model_name: my-custom-model
+    litellm_params:
+      model: azure/gpt-4o
+      api_key: os.environ/AZURE_API_KEY
+      api_base: os.environ/AZURE_API_BASE
+      api_version: os.environ/AZURE_API_VERSION
+```
+
+This way, you can maximize your rate limits across multiple model deployments. 
+
+## Fallbacks 
+
+You can fallback across model groups. This is useful, if all "model deployments" in a "model group" are down (e.g. raising 429 errors).
+
+Example:
+
+```yaml
+model_list:
+  - model_name: my-custom-model
+    litellm_params:
+      model: openai/gpt-4o-mini
+      api_key: os.environ/OPENAI_API_KEY
+  - model_name: my-other-model
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+
+litellm_settings:
+  fallbacks: [{"my-custom-model": ["my-other-model"]}]
+```
+
+Fallbacks are done sequentially, so the first model group in the list will be tried first. If it fails, the next model group will be tried.
\ No newline at end of file
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
index b45f6a459e..2f69f0e46c 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -246,6 +246,7 @@ const sidebars = {
           type: "category",
           label: "Model Access",
           items: [
+            "proxy/model_access_guide",
             "proxy/model_access",
             "proxy/team_model_add"
           ]
@@ -792,7 +793,6 @@ const sidebars = {
             "projects/GPTLocalhost",
             "projects/HolmesGPT",
             "projects/Railtracks",
-            "projects/Softgen",
           ],
         },
         "extras/code_quality",