From dcf5217d1764dc423805022d8600d3d36e2c851a Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Mon, 8 Dec 2025 18:05:50 -0300 Subject: [PATCH] docs: improve Getting Started page and SDK documentation structure (#17614) * docs: update Getting Started page with accurate endpoints and fix exception handling - Update endpoints list to include /responses, /audio, /batches - Change "Consistent output" to be endpoint-agnostic - Clarify Response Format title as "OpenAI Chat Completions Format" - Fix exception handling example: use litellm exceptions instead of deprecated openai.error - Add model prefix (anthropic/) to example * docs: reorganize sidebar and improve SDK documentation structure Sidebar changes: - Reorder: Python SDK first, then AI Gateway (Proxy) - Rename "LiteLLM - Getting Started" to "Getting Started" - Restructure SDK section with Core Functions, Configuration subsections - Move budget_manager to Guides - Move sdk_custom_pricing and migration to Extras - Remove duplicate embedding/async_embedding and embedding/moderation Content changes: - Add Response Format section to response_api.md - Add async aembedding() section to supported_embedding.md * docs: add deprecation notice for OpenAI Assistants API OpenAI has deprecated the Assistants API, shutting down on August 26, 2026. Added warning banner directing users to the Responses API. * docs: expand Core Functions in SDK sidebar Add more SDK functions to Core Functions category: - text_completion() - image_generation() - transcription() - speech() - Link to "All Supported Endpoints" for complete list * Rename Sidebar Item * docs: revert Getting Started label to original * Rename sidebar label from 'LiteLLM - Getting Started' to 'Getting Started' --- docs/my-website/docs/assistants.md | 8 ++ .../docs/embedding/supported_embedding.md | 20 ++++ docs/my-website/docs/index.md | 23 ++-- docs/my-website/docs/response_api.md | 32 ++++++ docs/my-website/sidebars.js | 100 ++++++++++++++---- 5 files changed, 152 insertions(+), 31 deletions(-) diff --git a/docs/my-website/docs/assistants.md b/docs/my-website/docs/assistants.md index d262b492a70..2960d0fded8 100644 --- a/docs/my-website/docs/assistants.md +++ b/docs/my-website/docs/assistants.md @@ -3,6 +3,14 @@ import TabItem from '@theme/TabItem'; # /assistants +:::warning Deprecation Notice + +OpenAI has deprecated the Assistants API. It will shut down on **August 26, 2026**. + +Consider migrating to the [Responses API](/docs/response_api) instead. See [OpenAI's migration guide](https://platform.openai.com/docs/guides/responses-vs-assistants) for details. + +::: + Covers Threads, Messages, Assistants. LiteLLM currently covers: diff --git a/docs/my-website/docs/embedding/supported_embedding.md b/docs/my-website/docs/embedding/supported_embedding.md index 0e8252b409b..11ca4da48a4 100644 --- a/docs/my-website/docs/embedding/supported_embedding.md +++ b/docs/my-website/docs/embedding/supported_embedding.md @@ -10,6 +10,26 @@ import os os.environ['OPENAI_API_KEY'] = "" response = embedding(model='text-embedding-ada-002', input=["good morning from litellm"]) ``` + +## Async Usage - `aembedding()` + +LiteLLM provides an asynchronous version of the `embedding` function called `aembedding`: + +```python +from litellm import aembedding +import asyncio + +async def get_embedding(): + response = await aembedding( + model='text-embedding-ada-002', + input=["good morning from litellm"] + ) + return response + +response = asyncio.run(get_embedding()) +print(response) +``` + ## Proxy Usage **NOTE** diff --git a/docs/my-website/docs/index.md b/docs/my-website/docs/index.md index 11d2963b7a3..c6e335e4cc3 100644 --- a/docs/my-website/docs/index.md +++ b/docs/my-website/docs/index.md @@ -7,8 +7,8 @@ https://github.com/BerriAI/litellm ## **Call 100+ LLMs using the OpenAI Input/Output Format** -- Translate inputs to provider's `completion`, `embedding`, and `image_generation` endpoints -- [Consistent output](https://docs.litellm.ai/docs/completion/output), text responses will always be available at `['choices'][0]['message']['content']` +- Translate inputs to provider's endpoints (`/chat/completions`, `/responses`, `/embeddings`, `/images`, `/audio`, `/batches`, and more) +- [Consistent output](https://docs.litellm.ai/docs/supported_endpoints) - same response format regardless of which provider you use - Retry/fallback logic across multiple deployments (e.g. Azure/OpenAI) - [Router](https://docs.litellm.ai/docs/routing) - Track spend & set budgets per project [LiteLLM Proxy Server](https://docs.litellm.ai/docs/simple_proxy) @@ -245,7 +245,7 @@ response = completion( -### Response Format (OpenAI Format) +### Response Format (OpenAI Chat Completions Format) ```json { @@ -514,15 +514,22 @@ response = completion( LiteLLM maps exceptions across all supported providers to the OpenAI exceptions. All our exceptions inherit from OpenAI's exception types, so any error-handling you have for that, should work out of the box with LiteLLM. ```python -from openai.error import OpenAIError +import litellm from litellm import completion +import os os.environ["ANTHROPIC_API_KEY"] = "bad-key" try: - # some code - completion(model="claude-instant-1", messages=[{"role": "user", "content": "Hey, how's it going?"}]) -except OpenAIError as e: - print(e) + completion(model="anthropic/claude-instant-1", messages=[{"role": "user", "content": "Hey, how's it going?"}]) +except litellm.AuthenticationError as e: + # Thrown when the API key is invalid + print(f"Authentication failed: {e}") +except litellm.RateLimitError as e: + # Thrown when you've exceeded your rate limit + print(f"Rate limited: {e}") +except litellm.APIError as e: + # Thrown for general API errors + print(f"API error: {e}") ``` ### See How LiteLLM Transforms Your Requests diff --git a/docs/my-website/docs/response_api.md b/docs/my-website/docs/response_api.md index 52e4c1e26f5..4e828c6c580 100644 --- a/docs/my-website/docs/response_api.md +++ b/docs/my-website/docs/response_api.md @@ -43,6 +43,38 @@ response = litellm.responses( print(response) ``` +#### Response Format (OpenAI Responses API Format) + +```json +{ + "id": "resp_abc123", + "object": "response", + "created_at": 1734366691, + "status": "completed", + "model": "o1-pro-2025-01-30", + "output": [ + { + "type": "message", + "id": "msg_abc123", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Once upon a time, a little unicorn named Stardust lived in a magical meadow where flowers sang lullabies. One night, she discovered that her horn could paint dreams across the sky, and she spent the evening creating the most beautiful aurora for all the forest creatures to enjoy. As the animals drifted off to sleep beneath her shimmering lights, Stardust curled up on a cloud of moonbeams, happy to have shared her magic with her friends.", + "annotations": [] + } + ] + } + ], + "usage": { + "input_tokens": 18, + "output_tokens": 98, + "total_tokens": 116 + } +} +``` + #### Streaming ```python showLineNumbers title="OpenAI Streaming Response" import litellm diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 583722a9393..1a0aa352390 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -118,11 +118,83 @@ const sidebars = { ], // But you can create a sidebar manually tutorialSidebar: [ - { type: "doc", id: "index" }, // NEW + { type: "doc", id: "index", label: "Getting Started" }, { type: "category", - label: "LiteLLM AI Gateway", + label: "LiteLLM Python SDK", + items: [ + { + type: "link", + label: "Quick Start", + href: "/docs/#litellm-python-sdk", + }, + { + type: "category", + label: "SDK Functions", + items: [ + { + type: "doc", + id: "completion/input", + label: "completion()", + }, + { + type: "doc", + id: "embedding/supported_embedding", + label: "embedding()", + }, + { + type: "doc", + id: "response_api", + label: "responses()", + }, + { + type: "doc", + id: "text_completion", + label: "text_completion()", + }, + { + type: "doc", + id: "image_generation", + label: "image_generation()", + }, + { + type: "doc", + id: "audio_transcription", + label: "transcription()", + }, + { + type: "doc", + id: "text_to_speech", + label: "speech()", + }, + { + type: "link", + label: "All Supported Endpoints →", + href: "/docs/supported_endpoints", + }, + ], + }, + { + type: "category", + label: "Configuration", + items: [ + "set_keys", + "caching/all_caches", + ], + }, + "completion/token_usage", + "exception_mapping", + { + type: "category", + label: "LangChain, LlamaIndex, Instructor", + items: ["langchain/langchain", "tutorials/instructor"], + } + ], + }, + { + type: "category", + label: "LiteLLM AI Gateway (Proxy)", link: { type: "generated-index", title: "LiteLLM AI Gateway (LLM Proxy)", @@ -696,6 +768,7 @@ const sidebars = { type: "category", label: "Guides", items: [ + "budget_manager", "completion/computer_use", "completion/web_search", "completion/web_fetch", @@ -748,27 +821,6 @@ const sidebars = { "wildcard_routing" ], }, - { - type: "category", - label: "LiteLLM Python SDK", - items: [ - "set_keys", - "budget_manager", - "caching/all_caches", - "completion/token_usage", - "sdk_custom_pricing", - "embedding/async_embedding", - "embedding/moderation", - "migration", - "sdk_custom_pricing", - { - type: "category", - label: "LangChain, LlamaIndex, Instructor Integration", - items: ["langchain/langchain", "tutorials/instructor"], - } - ], - }, - { type: "category", label: "Load Testing", @@ -838,6 +890,8 @@ const sidebars = { type: "category", label: "Extras", items: [ + "sdk_custom_pricing", + "migration", "data_security", "data_retention", "proxy/security_encryption_faq",