From f783505fb83e1d0e08a1cbce2111fc218e474e73 Mon Sep 17 00:00:00 2001 From: PhoenixCPH Date: Fri, 22 May 2026 02:41:44 +0800 Subject: [PATCH] docs: add multi-language README support Add Chinese, Spanish, French, Portuguese, Russian, and German README translations with a unified language switcher to improve onboarding for global SDK users. --- README-DE.md | 474 ++++++++++++++++++++++++++++++++++++++++++++++++++ README-ES.md | 483 +++++++++++++++++++++++++++++++++++++++++++++++++++ README-FR.md | 483 +++++++++++++++++++++++++++++++++++++++++++++++++++ README-PT.md | 474 ++++++++++++++++++++++++++++++++++++++++++++++++++ README-RU.md | 474 ++++++++++++++++++++++++++++++++++++++++++++++++++ README-ZH.md | 474 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 7 files changed, 2864 insertions(+) create mode 100644 README-DE.md create mode 100644 README-ES.md create mode 100644 README-FR.md create mode 100644 README-PT.md create mode 100644 README-RU.md create mode 100644 README-ZH.md diff --git a/README-DE.md b/README-DE.md new file mode 100644 index 0000000..55f4714 --- /dev/null +++ b/README-DE.md @@ -0,0 +1,474 @@ +# Groq Python-API-Bibliothek + +**Sprachen / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +Die Groq Python-Bibliothek bietet bequemen Zugriff auf die Groq REST API aus jeder Python-3.10+-Anwendung. Die Bibliothek enthält Typdefinitionen für alle Anfrageparameter und Antwortfelder und bietet sowohl synchrone als auch asynchrone Clients auf Basis von [httpx](https://github.com/encode/httpx). + +Sie wird mit [Stainless](https://www.stainless.com/) generiert. + +## Dokumentation + +Die REST-API-Dokumentation finden Sie auf [console.groq.com](https://console.groq.com/docs). Die vollständige API dieser Bibliothek ist in [api.md](api.md) dokumentiert. + +## Installation + +```sh +# install from PyPI +pip install groq +``` + +## Verwendung + +Die vollständige API dieser Bibliothek ist in [api.md](api.md) dokumentiert. + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +Obwohl Sie ein `api_key`-Schlüsselwortargument übergeben können, empfehlen wir die Verwendung von [python-dotenv](https://pypi.org/project/python-dotenv/), um `GROQ_API_KEY="My API Key"` zu Ihrer `.env`-Datei hinzuzufügen, damit Ihr API-Schlüssel nicht in der Versionskontrolle gespeichert wird. + +## Asynchrone Verwendung + +Importieren Sie einfach `AsyncGroq` anstelle von `Groq` und verwenden Sie `await` bei jedem API-Aufruf: + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +Die Funktionalität zwischen dem synchronen und dem asynchronen Client ist ansonsten identisch. + +### Mit aiohttp + +Standardmäßig verwendet der asynchrone Client `httpx` für HTTP-Anfragen. Für eine bessere Nebenläufigkeitsleistung können Sie jedoch auch `aiohttp` als HTTP-Backend verwenden. + +Sie können dies aktivieren, indem Sie `aiohttp` installieren: + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +Aktivieren Sie es dann, indem Sie den Client mit `http_client=DefaultAioHttpClient()` instanziieren: + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## Typen verwenden + +Verschachtelte Anfrageparameter sind [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Antworten sind [Pydantic-Modelle](https://docs.pydantic.dev), die auch Hilfsmethoden für folgende Aufgaben bereitstellen: + +- Zurückserialisieren in JSON, `model.to_json()` +- Umwandeln in ein Dictionary, `model.to_dict()` + +Typisierte Anfragen und Antworten bieten Autovervollständigung und Dokumentation in Ihrem Editor. Wenn Sie Typfehler in VS Code sehen möchten, um Fehler früher zu erkennen, setzen Sie `python.analysis.typeCheckingMode` auf `basic`. + +## Verschachtelte Parameter + +Verschachtelte Parameter sind Dictionaries, die mit `TypedDict` typisiert sind, zum Beispiel: + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## Datei-Uploads + +Anfrageparameter, die Datei-Uploads entsprechen, können als `bytes`, als [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike)-Instanz oder als Tupel `(filename, contents, media type)` übergeben werden. + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +Der asynchrone Client verwendet exakt dieselbe Schnittstelle. Wenn Sie eine [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike)-Instanz übergeben, wird der Dateiinhalt automatisch asynchron gelesen. + +## Fehlerbehandlung + +Wenn die Bibliothek keine Verbindung zur API herstellen kann (z. B. aufgrund von Netzwerkverbindungsproblemen oder einem Timeout), wird eine Unterklasse von `groq.APIConnectionError` ausgelöst. + +Wenn die API einen Nicht-Erfolgs-Statuscode zurückgibt (d. h. 4xx- oder 5xx-Antwort), wird eine Unterklasse von `groq.APIStatusError` ausgelöst, die die Eigenschaften `status_code` und `response` enthält. + +Alle Fehler erben von `groq.APIError`. + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Die Fehlercodes sind wie folgt: + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### Wiederholungsversuche + +Bestimmte Fehler werden standardmäßig automatisch 2-mal wiederholt, mit einem kurzen exponentiellen Backoff. Verbindungsfehler (z. B. aufgrund eines Netzwerkverbindungsproblems), 408 Request Timeout, 409 Conflict, 429 Rate Limit und >=500 Internal Errors werden alle standardmäßig wiederholt. + +Sie können die Option `max_retries` verwenden, um Wiederholungseinstellungen zu konfigurieren oder zu deaktivieren: + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### Timeouts + +Standardmäßig laufen Anfragen nach 1 Minute ab. Sie können dies mit der Option `timeout` konfigurieren, die einen Float oder ein [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration)-Objekt akzeptiert: + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +Bei einem Timeout wird ein `APITimeoutError` ausgelöst. + +Beachten Sie, dass Anfragen, die ablaufen, [standardmäßig zweimal wiederholt werden](#wiederholungsversuche). + +## Erweitert + +### Logging + +Wir verwenden das Modul [`logging`](https://docs.python.org/3/library/logging.html) der Standardbibliothek. + +Sie können Logging aktivieren, indem Sie die Umgebungsvariable `GROQ_LOG` auf `info` setzen. + +```shell +$ export GROQ_LOG=info +``` + +Oder auf `debug` für ausführlicheres Logging. + +### Wie man erkennt, ob `None` `null` oder fehlend bedeutet + +In einer API-Antwort kann ein Feld explizit `null` sein oder vollständig fehlen; in beiden Fällen ist sein Wert in dieser Bibliothek `None`. Sie können die beiden Fälle mit `.model_fields_set` unterscheiden: + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Zugriff auf Rohdaten der Antwort (z. B. Header) + +Auf das „rohe“ Response-Objekt kann zugegriffen werden, indem `.with_raw_response.` vor jeden HTTP-Methodenaufruf gesetzt wird, z. B.: + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +Diese Methoden geben ein [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py)-Objekt zurück. + +Der asynchrone Client gibt ein [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) mit derselben Struktur zurück; der einzige Unterschied sind `await`-fähige Methoden zum Lesen des Antwortinhalts. + +#### `.with_streaming_response` + +Die obige Schnittstelle liest den vollständigen Antwortbody beim Senden der Anfrage sofort ein, was nicht immer gewünscht ist. + +Um den Antwortbody zu streamen, verwenden Sie stattdessen `.with_streaming_response`, was einen Kontextmanager erfordert und den Antwortbody erst liest, wenn Sie `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` oder `.parse()` aufrufen. Im asynchronen Client sind dies asynchrone Methoden. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +Der Kontextmanager ist erforderlich, damit die Antwort zuverlässig geschlossen wird. + +### Benutzerdefinierte/undokumentierte Anfragen + +Diese Bibliothek ist für den bequemen Zugriff auf die dokumentierte API typisiert. + +Wenn Sie auf undokumentierte Endpunkte, Parameter oder Antworteigenschaften zugreifen müssen, kann die Bibliothek dennoch verwendet werden. + +#### Undokumentierte Endpunkte + +Um Anfragen an undokumentierte Endpunkte zu senden, können Sie `client.get`, `client.post` und andere HTTP-Verben verwenden. Client-Optionen (wie Wiederholungsversuche) werden bei dieser Anfrage berücksichtigt. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Undokumentierte Anfrageparameter + +Wenn Sie explizit einen zusätzlichen Parameter senden möchten, können Sie dies mit den Anfrageoptionen `extra_query`, `extra_body` und `extra_headers` tun. + +#### Undokumentierte Antworteigenschaften + +Um auf undokumentierte Antworteigenschaften zuzugreifen, können Sie auf die zusätzlichen Felder wie `response.unknown_prop` zugreifen. Sie können auch alle zusätzlichen Felder im Pydantic-Modell als Dictionary mit [`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra) abrufen. + +### Konfiguration des HTTP-Clients + +Sie können den [httpx-Client](https://www.python-httpx.org/api/#client) direkt überschreiben, um ihn für Ihren Anwendungsfall anzupassen, einschließlich: + +- Unterstützung für [Proxies](https://www.python-httpx.org/advanced/proxies/) +- Benutzerdefinierte [Transports](https://www.python-httpx.org/advanced/transports/) +- Zusätzliche [erweiterte](https://www.python-httpx.org/advanced/clients/) Funktionalität + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +Sie können den Client auch pro Anfrage mit `with_options()` anpassen: + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Verwaltung von HTTP-Ressourcen + +Standardmäßig schließt die Bibliothek die zugrunde liegenden HTTP-Verbindungen, wenn der Client [vom Garbage Collector freigegeben](https://docs.python.org/3/reference/datamodel.html#object.__del__) wird. Sie können den Client bei Bedarf manuell mit der Methode `.close()` schließen oder mit einem Kontextmanager, der beim Verlassen schließt. + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Versionierung + +Dieses Paket folgt im Allgemeinen den [SemVer](https://semver.org/spec/v2.0.0.html)-Konventionen, obwohl bestimmte rückwärtsinkompatible Änderungen als Minor-Versionen veröffentlicht werden können: + +1. Änderungen, die nur statische Typen betreffen, ohne das Laufzeitverhalten zu beeinträchtigen. +2. Änderungen an Bibliotheksinterna, die technisch öffentlich sind, aber nicht für die externe Nutzung vorgesehen oder dokumentiert sind. _(Bitte öffnen Sie ein GitHub-Issue, wenn Sie auf solche Interna angewiesen sind.)_ +3. Änderungen, von denen wir nicht erwarten, dass sie die überwiegende Mehrheit der Benutzer in der Praxis betreffen. + +Wir nehmen Rückwärtskompatibilität ernst und arbeiten daran, Ihnen ein reibungsloses Upgrade-Erlebnis zu bieten. + +Wir freuen uns über Ihr Feedback; öffnen Sie bitte ein [Issue](https://www.github.com/groq/groq-python/issues) mit Fragen, Fehlern oder Vorschlägen. + +### Ermittlung der installierten Version + +Wenn Sie auf die neueste Version aktualisiert haben, aber keine neuen Funktionen sehen, die Sie erwartet haben, verwendet Ihre Python-Umgebung wahrscheinlich noch eine ältere Version. + +Sie können die zur Laufzeit verwendete Version wie folgt ermitteln: + +```py +import groq +print(groq.__version__) +``` + +## Anforderungen + +Python 3.10 oder höher. + +## Mitwirken + +Siehe [die Mitwirkungsdokumentation](./CONTRIBUTING.md). diff --git a/README-ES.md b/README-ES.md new file mode 100644 index 0000000..f321609 --- /dev/null +++ b/README-ES.md @@ -0,0 +1,483 @@ +# Biblioteca Python de la API de Groq + +**Idiomas / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +La biblioteca Python de Groq ofrece un acceso conveniente a la API REST de Groq desde cualquier aplicación Python 3.10 o superior. La biblioteca incluye definiciones de tipos para todos los parámetros de solicitud y campos de respuesta, y ofrece clientes síncronos y asíncronos impulsados por [httpx](https://github.com/encode/httpx). + +Está generada con [Stainless](https://www.stainless.com/). + +## Documentación + +La documentación de la API REST se encuentra en [console.groq.com](https://console.groq.com/docs). La API completa de esta biblioteca está en [api.md](api.md). + +## Instalación + +```sh +# install from PyPI +pip install groq +``` + +## Uso + +La API completa de esta biblioteca está en [api.md](api.md). + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +Aunque puedes proporcionar un argumento de palabra clave `api_key`, +recomendamos usar [python-dotenv](https://pypi.org/project/python-dotenv/) +para añadir `GROQ_API_KEY="My API Key"` a tu archivo `.env` +de modo que tu clave de API no quede almacenada en el control de versiones. + +## Uso asíncrono + +Simplemente importa `AsyncGroq` en lugar de `Groq` y usa `await` en cada llamada a la API: + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +La funcionalidad entre los clientes síncrono y asíncrono es idéntica en lo demás. + +### Con aiohttp + +Por defecto, el cliente asíncrono usa `httpx` para las solicitudes HTTP. Sin embargo, para mejorar el rendimiento de concurrencia también puedes usar `aiohttp` como backend HTTP. + +Puedes habilitarlo instalando `aiohttp`: + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +Luego puedes habilitarlo instanciando el cliente con `http_client=DefaultAioHttpClient()`: + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## Uso de tipos + +Los parámetros de solicitud anidados son [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Las respuestas son [modelos Pydantic](https://docs.pydantic.dev) que también ofrecen métodos auxiliares para cosas como: + +- Serializar de nuevo a JSON, `model.to_json()` +- Convertir a un diccionario, `model.to_dict()` + +Las solicitudes y respuestas tipadas proporcionan autocompletado y documentación en tu editor. Si deseas ver errores de tipo en VS Code para detectar errores antes, establece `python.analysis.typeCheckingMode` en `basic`. + +## Parámetros anidados + +Los parámetros anidados son diccionarios, tipados con `TypedDict`, por ejemplo: + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## Carga de archivos + +Los parámetros de solicitud que corresponden a cargas de archivos pueden pasarse como `bytes`, una instancia de [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) o una tupla de `(filename, contents, media type)`. + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +El cliente asíncrono usa exactamente la misma interfaz. Si pasas una instancia de [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike), el contenido del archivo se leerá de forma asíncrona automáticamente. + +## Manejo de errores + +Cuando la biblioteca no puede conectarse a la API (por ejemplo, debido a problemas de conexión de red o un tiempo de espera), se lanza una subclase de `groq.APIConnectionError`. + +Cuando la API devuelve un código de estado que no indica éxito (es decir, respuesta 4xx o 5xx), se lanza una subclase de `groq.APIStatusError`, que contiene las propiedades `status_code` y `response`. + +Todos los errores heredan de `groq.APIError`. + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Los códigos de error son los siguientes: + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### Reintentos + +Ciertos errores se reintentan automáticamente 2 veces por defecto, con un breve retroceso exponencial. +Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, +429 Rate Limit y errores internos >=500 se reintentan por defecto. + +Puedes usar la opción `max_retries` para configurar o deshabilitar los ajustes de reintento: + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### Tiempos de espera + +Por defecto, las solicitudes agotan el tiempo de espera tras 1 minuto. Puedes configurarlo con la opción `timeout`, +que acepta un float o un objeto [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration): + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +En caso de tiempo de espera, se lanza un `APITimeoutError`. + +Ten en cuenta que las solicitudes que agotan el tiempo de espera [se reintentan dos veces por defecto](#reintentos). + +## Avanzado + +### Registro + +Usamos el módulo estándar [`logging`](https://docs.python.org/3/library/logging.html). + +Puedes habilitar el registro estableciendo la variable de entorno `GROQ_LOG` en `info`. + +```shell +$ export GROQ_LOG=info +``` + +O en `debug` para un registro más detallado. + +### Cómo saber si `None` significa `null` o ausente + +En una respuesta de la API, un campo puede ser explícitamente `null` o estar completamente ausente; en cualquier caso, su valor es `None` en esta biblioteca. Puedes diferenciar los dos casos con `.model_fields_set`: + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Acceso a datos de respuesta sin procesar (p. ej. headers) + +Se puede acceder al objeto Response «sin procesar» anteponiendo `.with_raw_response.` a cualquier llamada de método HTTP, p. ej.: + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +Estos métodos devuelven un objeto [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py). + +El cliente asíncrono devuelve un [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) con la misma estructura; la única diferencia son los métodos que requieren `await` para leer el contenido de la respuesta. + +#### `.with_streaming_response` + +La interfaz anterior lee con avidez el cuerpo completo de la respuesta al hacer la solicitud, lo cual puede no ser siempre lo que deseas. + +Para transmitir el cuerpo de la respuesta, usa `.with_streaming_response` en su lugar, que requiere un administrador de contexto y solo lee el cuerpo de la respuesta cuando llamas a `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` o `.parse()`. En el cliente asíncrono, estos son métodos asíncronos. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +El administrador de contexto es necesario para que la respuesta se cierre de forma fiable. + +### Realizar solicitudes personalizadas/no documentadas + +Esta biblioteca está tipada para un acceso conveniente a la API documentada. + +Si necesitas acceder a endpoints, parámetros o propiedades de respuesta no documentados, la biblioteca sigue siendo utilizable. + +#### Endpoints no documentados + +Para hacer solicitudes a endpoints no documentados, puedes usar `client.get`, `client.post` y otros +verbos http. Las opciones del cliente se respetarán (como los reintentos) al hacer esta solicitud. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Parámetros de solicitud no documentados + +Si deseas enviar explícitamente un parámetro adicional, puedes hacerlo con las opciones de solicitud `extra_query`, `extra_body` y `extra_headers`. + +#### Propiedades de respuesta no documentadas + +Para acceder a propiedades de respuesta no documentadas, puedes acceder a los campos adicionales como `response.unknown_prop`. También +puedes obtener todos los campos adicionales del modelo Pydantic como un diccionario con +[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). + +### Configuración del cliente HTTP + +Puedes sobrescribir directamente el [cliente httpx](https://www.python-httpx.org/api/#client) para personalizarlo según tu caso de uso, incluyendo: + +- Soporte para [proxies](https://www.python-httpx.org/advanced/proxies/) +- [Transportes](https://www.python-httpx.org/advanced/transports/) personalizados +- Funcionalidad [avanzada](https://www.python-httpx.org/advanced/clients/) adicional + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +También puedes personalizar el cliente por solicitud usando `with_options()`: + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Gestión de recursos HTTP + +Por defecto, la biblioteca cierra las conexiones HTTP subyacentes cuando el cliente es [recolectado por el recolector de basura](https://docs.python.org/3/reference/datamodel.html#object.__del__). Puedes cerrar el cliente manualmente con el método `.close()` si lo deseas, o con un administrador de contexto que se cierra al salir. + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Versionado + +Este paquete generalmente sigue las convenciones de [SemVer](https://semver.org/spec/v2.0.0.html), aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores: + +1. Cambios que solo afectan a tipos estáticos, sin romper el comportamiento en tiempo de ejecución. +2. Cambios en los internos de la biblioteca que son técnicamente públicos pero no están destinados ni documentados para uso externo. _(Abre un issue en GitHub para informarnos si dependes de dichos internos.)_ +3. Cambios que no esperamos que afecten a la gran mayoría de usuarios en la práctica. + +Nos tomamos en serio la compatibilidad hacia atrás y trabajamos para que puedas contar con una experiencia de actualización fluida. + +Agradecemos tus comentarios; abre un [issue](https://www.github.com/groq/groq-python/issues) con preguntas, errores o sugerencias. + +### Determinar la versión instalada + +Si has actualizado a la última versión pero no ves las nuevas funciones que esperabas, es probable que tu entorno de Python siga usando una versión anterior. + +Puedes determinar la versión que se usa en tiempo de ejecución con: + +```py +import groq +print(groq.__version__) +``` + +## Requisitos + +Python 3.10 o superior. + +## Contribuir + +Consulta [la documentación de contribución](./CONTRIBUTING.md). diff --git a/README-FR.md b/README-FR.md new file mode 100644 index 0000000..57dda7f --- /dev/null +++ b/README-FR.md @@ -0,0 +1,483 @@ +# Bibliothèque Python de l'API Groq + +**Langues / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +La bibliothèque Python Groq offre un accès pratique à l'API REST Groq depuis toute application Python 3.10 ou supérieure. La bibliothèque inclut des définitions de types pour tous les paramètres de requête et champs de réponse, et propose des clients synchrones et asynchrones propulsés par [httpx](https://github.com/encode/httpx). + +Elle est générée avec [Stainless](https://www.stainless.com/). + +## Documentation + +La documentation de l'API REST se trouve sur [console.groq.com](https://console.groq.com/docs). L'API complète de cette bibliothèque est disponible dans [api.md](api.md). + +## Installation + +```sh +# install from PyPI +pip install groq +``` + +## Utilisation + +L'API complète de cette bibliothèque est disponible dans [api.md](api.md). + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +Bien que vous puissiez fournir un argument nommé `api_key`, +nous recommandons d'utiliser [python-dotenv](https://pypi.org/project/python-dotenv/) +pour ajouter `GROQ_API_KEY="My API Key"` à votre fichier `.env` +afin que votre clé API ne soit pas stockée dans le contrôle de version. + +## Utilisation asynchrone + +Importez simplement `AsyncGroq` au lieu de `Groq` et utilisez `await` pour chaque appel API : + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +La fonctionnalité entre les clients synchrones et asynchrones est par ailleurs identique. + +### Avec aiohttp + +Par défaut, le client asynchrone utilise `httpx` pour les requêtes HTTP. Cependant, pour de meilleures performances de concurrence, vous pouvez aussi utiliser `aiohttp` comme backend HTTP. + +Vous pouvez l'activer en installant `aiohttp` : + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +Puis activez-le en instanciant le client avec `http_client=DefaultAioHttpClient()` : + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## Utilisation des types + +Les paramètres de requête imbriqués sont des [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Les réponses sont des [modèles Pydantic](https://docs.pydantic.dev) qui fournissent également des méthodes utilitaires pour notamment : + +- Sérialiser en JSON, `model.to_json()` +- Convertir en dictionnaire, `model.to_dict()` + +Les requêtes et réponses typées offrent l'autocomplétion et la documentation dans votre éditeur. Si vous souhaitez voir les erreurs de type dans VS Code pour détecter les bugs plus tôt, définissez `python.analysis.typeCheckingMode` sur `basic`. + +## Paramètres imbriqués + +Les paramètres imbriqués sont des dictionnaires, typés avec `TypedDict`, par exemple : + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## Téléversement de fichiers + +Les paramètres de requête correspondant à des téléversements de fichiers peuvent être passés sous forme de `bytes`, d'une instance [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) ou d'un tuple `(filename, contents, media type)`. + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +Le client asynchrone utilise exactement la même interface. Si vous passez une instance [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike), le contenu du fichier sera lu de manière asynchrone automatiquement. + +## Gestion des erreurs + +Lorsque la bibliothèque ne peut pas se connecter à l'API (par exemple en raison de problèmes de connexion réseau ou d'un délai d'attente), une sous-classe de `groq.APIConnectionError` est levée. + +Lorsque l'API renvoie un code d'état non réussi (c'est-à-dire une réponse 4xx ou 5xx), une sous-classe de `groq.APIStatusError` est levée, contenant les propriétés `status_code` et `response`. + +Toutes les erreurs héritent de `groq.APIError`. + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Les codes d'erreur sont les suivants : + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### Nouvelles tentatives + +Certaines erreurs sont automatiquement réessayées 2 fois par défaut, avec un court backoff exponentiel. +Les erreurs de connexion (par exemple dues à un problème de connectivité réseau), 408 Request Timeout, 409 Conflict, +429 Rate Limit et les erreurs internes >=500 sont toutes réessayées par défaut. + +Vous pouvez utiliser l'option `max_retries` pour configurer ou désactiver les paramètres de nouvelle tentative : + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### Délais d'attente + +Par défaut, les requêtes expirent après 1 minute. Vous pouvez configurer cela avec l'option `timeout`, +qui accepte un float ou un objet [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) : + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +En cas de délai d'attente, une `APITimeoutError` est levée. + +Notez que les requêtes expirées sont [réessayées deux fois par défaut](#nouvelles-tentatives). + +## Avancé + +### Journalisation + +Nous utilisons le module standard [`logging`](https://docs.python.org/3/library/logging.html). + +Vous pouvez activer la journalisation en définissant la variable d'environnement `GROQ_LOG` sur `info`. + +```shell +$ export GROQ_LOG=info +``` + +Ou sur `debug` pour une journalisation plus détaillée. + +### Comment savoir si `None` signifie `null` ou absent + +Dans une réponse API, un champ peut être explicitement `null`, ou entièrement absent ; dans les deux cas, sa valeur est `None` dans cette bibliothèque. Vous pouvez différencier les deux cas avec `.model_fields_set` : + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Accès aux données de réponse brutes (p. ex. headers) + +L'objet Response « brut » est accessible en préfixant `.with_raw_response.` à tout appel de méthode HTTP, par ex. : + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +Ces méthodes renvoient un objet [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py). + +Le client asynchrone renvoie un [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) de même structure ; la seule différence est que les méthodes de lecture du contenu de la réponse sont `await`ables. + +#### `.with_streaming_response` + +L'interface ci-dessus lit immédiatement l'intégralité du corps de la réponse lors de la requête, ce qui n'est pas toujours souhaitable. + +Pour diffuser le corps de la réponse, utilisez plutôt `.with_streaming_response`, qui nécessite un gestionnaire de contexte et ne lit le corps de la réponse que lorsque vous appelez `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` ou `.parse()`. Dans le client asynchrone, ce sont des méthodes asynchrones. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +Le gestionnaire de contexte est requis pour que la réponse soit fermée de manière fiable. + +### Requêtes personnalisées/non documentées + +Cette bibliothèque est typée pour un accès pratique à l'API documentée. + +Si vous devez accéder à des points de terminaison, paramètres ou propriétés de réponse non documentés, la bibliothèque reste utilisable. + +#### Points de terminaison non documentés + +Pour faire des requêtes vers des points de terminaison non documentés, vous pouvez utiliser `client.get`, `client.post` et d'autres +verbes http. Les options du client seront respectées (comme les nouvelles tentatives) lors de cette requête. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Paramètres de requête non documentés + +Si vous souhaitez envoyer explicitement un paramètre supplémentaire, vous pouvez le faire avec les options de requête `extra_query`, `extra_body` et `extra_headers`. + +#### Propriétés de réponse non documentées + +Pour accéder à des propriétés de réponse non documentées, vous pouvez accéder aux champs supplémentaires comme `response.unknown_prop`. Vous +pouvez aussi obtenir tous les champs supplémentaires du modèle Pydantic sous forme de dictionnaire avec +[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). + +### Configuration du client HTTP + +Vous pouvez directement remplacer le [client httpx](https://www.python-httpx.org/api/#client) pour l'adapter à votre cas d'usage, notamment : + +- Prise en charge des [proxies](https://www.python-httpx.org/advanced/proxies/) +- [Transports](https://www.python-httpx.org/advanced/transports/) personnalisés +- Fonctionnalités [avancées](https://www.python-httpx.org/advanced/clients/) supplémentaires + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +Vous pouvez aussi personnaliser le client par requête avec `with_options()` : + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Gestion des ressources HTTP + +Par défaut, la bibliothèque ferme les connexions HTTP sous-jacentes lorsque le client est [collecté par le ramasse-miettes](https://docs.python.org/3/reference/datamodel.html#object.__del__). Vous pouvez fermer le client manuellement avec la méthode `.close()` si vous le souhaitez, ou avec un gestionnaire de contexte qui se ferme à la sortie. + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Versionnement + +Ce paquet suit généralement les conventions [SemVer](https://semver.org/spec/v2.0.0.html), bien que certains changements incompatibles avec les versions antérieures puissent être publiés en versions mineures : + +1. Changements qui n'affectent que les types statiques, sans casser le comportement à l'exécution. +2. Changements des internes de la bibliothèque qui sont techniquement publics mais non destinés ni documentés pour un usage externe. _(Veuillez ouvrir une issue GitHub pour nous indiquer si vous vous appuyez sur ces internes.)_ +3. Changements que nous ne prévoyons pas d'impacter la grande majorité des utilisateurs en pratique. + +Nous prenons la rétrocompatibilité au sérieux et travaillons pour que vous puissiez compter sur une mise à niveau fluide. + +Nous accueillons vos retours ; ouvrez une [issue](https://www.github.com/groq/groq-python/issues) pour des questions, bugs ou suggestions. + +### Déterminer la version installée + +Si vous avez mis à jour vers la dernière version mais ne voyez pas les nouvelles fonctionnalités attendues, votre environnement Python utilise probablement encore une version plus ancienne. + +Vous pouvez déterminer la version utilisée à l'exécution avec : + +```py +import groq +print(groq.__version__) +``` + +## Prérequis + +Python 3.10 ou supérieur. + +## Contribution + +Voir [la documentation de contribution](./CONTRIBUTING.md). diff --git a/README-PT.md b/README-PT.md new file mode 100644 index 0000000..f20bf9c --- /dev/null +++ b/README-PT.md @@ -0,0 +1,474 @@ +# Biblioteca Python da API Groq + +**Idiomas / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +A biblioteca Python da Groq oferece acesso conveniente à API REST da Groq a partir de qualquer aplicação Python 3.10+. A biblioteca inclui definições de tipos para todos os parâmetros de requisição e campos de resposta, e oferece clientes síncronos e assíncronos baseados em [httpx](https://github.com/encode/httpx). + +Ela é gerada com [Stainless](https://www.stainless.com/). + +## Documentação + +A documentação da API REST pode ser encontrada em [console.groq.com](https://console.groq.com/docs). A API completa desta biblioteca está em [api.md](api.md). + +## Instalação + +```sh +# install from PyPI +pip install groq +``` + +## Uso + +A API completa desta biblioteca está em [api.md](api.md). + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +Embora seja possível fornecer um argumento de palavra-chave `api_key`, recomendamos usar [python-dotenv](https://pypi.org/project/python-dotenv/) para adicionar `GROQ_API_KEY="My API Key"` ao seu arquivo `.env`, de modo que sua chave de API não fique armazenada no controle de versão. + +## Uso assíncrono + +Basta importar `AsyncGroq` em vez de `Groq` e usar `await` em cada chamada à API: + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +A funcionalidade entre os clientes síncrono e assíncrono é, de resto, idêntica. + +### Com aiohttp + +Por padrão, o cliente assíncrono usa `httpx` para requisições HTTP. No entanto, para melhor desempenho de concorrência, você também pode usar `aiohttp` como backend HTTP. + +Você pode habilitar isso instalando `aiohttp`: + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +Em seguida, habilite-o instanciando o cliente com `http_client=DefaultAioHttpClient()`: + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## Usando tipos + +Parâmetros de requisição aninhados são [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). As respostas são [modelos Pydantic](https://docs.pydantic.dev), que também fornecem métodos auxiliares para coisas como: + +- Serializar de volta para JSON, `model.to_json()` +- Converter para um dicionário, `model.to_dict()` + +Requisições e respostas tipadas oferecem autocompletar e documentação no seu editor. Se quiser ver erros de tipo no VS Code para ajudar a detectar bugs mais cedo, defina `python.analysis.typeCheckingMode` como `basic`. + +## Parâmetros aninhados + +Parâmetros aninhados são dicionários, tipados com `TypedDict`, por exemplo: + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## Upload de arquivos + +Parâmetros de requisição que correspondem a uploads de arquivos podem ser passados como `bytes`, uma instância de [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) ou uma tupla `(filename, contents, media type)`. + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +O cliente assíncrono usa exatamente a mesma interface. Se você passar uma instância de [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike), o conteúdo do arquivo será lido de forma assíncrona automaticamente. + +## Tratamento de erros + +Quando a biblioteca não consegue se conectar à API (por exemplo, devido a problemas de conexão de rede ou timeout), uma subclasse de `groq.APIConnectionError` é lançada. + +Quando a API retorna um código de status de falha (ou seja, resposta 4xx ou 5xx), uma subclasse de `groq.APIStatusError` é lançada, contendo as propriedades `status_code` e `response`. + +Todos os erros herdam de `groq.APIError`. + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Os códigos de erro são os seguintes: + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### Tentativas novas + +Certos erros são automaticamente repetidos 2 vezes por padrão, com um backoff exponencial curto. Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit e erros internos >=500 são todos repetidos por padrão. + +Você pode usar a opção `max_retries` para configurar ou desabilitar as configurações de repetição: + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### Timeouts + +Por padrão, as requisições expiram após 1 minuto. Você pode configurar isso com a opção `timeout`, que aceita um float ou um objeto [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration): + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +Em caso de timeout, um `APITimeoutError` é lançado. + +Observe que requisições que expiram são [repetidas duas vezes por padrão](#tentativas-novas). + +## Avançado + +### Logging + +Usamos o módulo [`logging`](https://docs.python.org/3/library/logging.html) da biblioteca padrão. + +Você pode habilitar o logging definindo a variável de ambiente `GROQ_LOG` como `info`. + +```shell +$ export GROQ_LOG=info +``` + +Ou como `debug` para logging mais detalhado. + +### Como saber se `None` significa `null` ou ausente + +Em uma resposta da API, um campo pode ser explicitamente `null` ou estar totalmente ausente; em ambos os casos, seu valor é `None` nesta biblioteca. Você pode diferenciar os dois casos com `.model_fields_set`: + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Acessando dados brutos da resposta (ex.: cabeçalhos) + +O objeto Response "bruto" pode ser acessado prefixando `.with_raw_response.` a qualquer chamada de método HTTP, por exemplo: + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +Esses métodos retornam um objeto [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py). + +O cliente assíncrono retorna um [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) com a mesma estrutura; a única diferença são métodos `await` para ler o conteúdo da resposta. + +#### `.with_streaming_response` + +A interface acima lê ansiosamente o corpo completo da resposta quando você faz a requisição, o que nem sempre é o desejado. + +Para transmitir o corpo da resposta, use `.with_streaming_response` em vez disso, o que requer um gerenciador de contexto e só lê o corpo da resposta quando você chama `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` ou `.parse()`. No cliente assíncrono, esses são métodos assíncronos. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +O gerenciador de contexto é necessário para que a resposta seja fechada de forma confiável. + +### Fazendo requisições personalizadas/não documentadas + +Esta biblioteca é tipada para acesso conveniente à API documentada. + +Se precisar acessar endpoints, parâmetros ou propriedades de resposta não documentados, a biblioteca ainda pode ser usada. + +#### Endpoints não documentados + +Para fazer requisições a endpoints não documentados, você pode usar `client.get`, `client.post` e outros verbos HTTP. As opções do cliente serão respeitadas (como tentativas novas) ao fazer essa requisição. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Parâmetros de requisição não documentados + +Se quiser enviar explicitamente um parâmetro extra, você pode fazê-lo com as opções de requisição `extra_query`, `extra_body` e `extra_headers`. + +#### Propriedades de resposta não documentadas + +Para acessar propriedades de resposta não documentadas, você pode acessar os campos extras como `response.unknown_prop`. Você também pode obter todos os campos extras no modelo Pydantic como um dicionário com [`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). + +### Configurando o cliente HTTP + +Você pode substituir diretamente o [cliente httpx](https://www.python-httpx.org/api/#client) para personalizá-lo para o seu caso de uso, incluindo: + +- Suporte a [proxies](https://www.python-httpx.org/advanced/proxies/) +- [Transports](https://www.python-httpx.org/advanced/transports/) personalizados +- Funcionalidades [avançadas](https://www.python-httpx.org/advanced/clients/) adicionais + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +Você também pode personalizar o cliente por requisição usando `with_options()`: + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Gerenciando recursos HTTP + +Por padrão, a biblioteca fecha as conexões HTTP subjacentes sempre que o cliente é [coletado pelo garbage collector](https://docs.python.org/3/reference/datamodel.html#object.__del__). Você pode fechar manualmente o cliente usando o método `.close()` se desejar, ou com um gerenciador de contexto que fecha ao sair. + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Versionamento + +Este pacote geralmente segue as convenções [SemVer](https://semver.org/spec/v2.0.0.html), embora certas alterações incompatíveis com versões anteriores possam ser lançadas como versões menores: + +1. Alterações que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução. +2. Alterações em detalhes internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo. _(Abra uma issue no GitHub para nos informar se você depende de tais detalhes internos.)_ +3. Alterações que não esperamos impactar a grande maioria dos usuários na prática. + +Levamos a compatibilidade com versões anteriores a sério e trabalhamos para garantir uma experiência de atualização tranquila. + +Valorizamos seu feedback; abra uma [issue](https://www.github.com/groq/groq-python/issues) com dúvidas, bugs ou sugestões. + +### Determinando a versão instalada + +Se você atualizou para a versão mais recente, mas não está vendo os novos recursos que esperava, é provável que seu ambiente Python ainda esteja usando uma versão mais antiga. + +Você pode determinar a versão usada em tempo de execução com: + +```py +import groq +print(groq.__version__) +``` + +## Requisitos + +Python 3.10 ou superior. + +## Contribuindo + +Consulte [a documentação de contribuição](./CONTRIBUTING.md). diff --git a/README-RU.md b/README-RU.md new file mode 100644 index 0000000..29c3e2c --- /dev/null +++ b/README-RU.md @@ -0,0 +1,474 @@ +# Python-библиотека API Groq + +**Языки / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +Python-библиотека Groq обеспечивает удобный доступ к REST API Groq из любого приложения на Python 3.10+. Библиотека включает определения типов для всех параметров запросов и полей ответов, а также предоставляет синхронные и асинхронные клиенты на базе [httpx](https://github.com/encode/httpx). + +Она сгенерирована с помощью [Stainless](https://www.stainless.com/). + +## Документация + +Документация REST API доступна на [console.groq.com](https://console.groq.com/docs). Полный API этой библиотеки описан в [api.md](api.md). + +## Установка + +```sh +# install from PyPI +pip install groq +``` + +## Использование + +Полный API этой библиотеки описан в [api.md](api.md). + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +Хотя вы можете передать ключевой аргумент `api_key`, мы рекомендуем использовать [python-dotenv](https://pypi.org/project/python-dotenv/) для добавления `GROQ_API_KEY="My API Key"` в ваш файл `.env`, чтобы API-ключ не хранился в системе контроля версий. + +## Асинхронное использование + +Просто импортируйте `AsyncGroq` вместо `Groq` и используйте `await` с каждым вызовом API: + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +Функциональность синхронного и асинхронного клиентов в остальном идентична. + +### С aiohttp + +По умолчанию асинхронный клиент использует `httpx` для HTTP-запросов. Однако для улучшения производительности при конкурентном доступе вы также можете использовать `aiohttp` в качестве HTTP-бэкенда. + +Вы можете включить это, установив `aiohttp`: + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +Затем включите его, создав экземпляр клиента с `http_client=DefaultAioHttpClient()`: + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## Использование типов + +Вложенные параметры запросов — это [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Ответы — это [модели Pydantic](https://docs.pydantic.dev), которые также предоставляют вспомогательные методы для таких операций, как: + +- Сериализация обратно в JSON, `model.to_json()` +- Преобразование в словарь, `model.to_dict()` + +Типизированные запросы и ответы обеспечивают автодополнение и документацию в вашем редакторе. Если вы хотите видеть ошибки типов в VS Code для раннего обнаружения ошибок, установите `python.analysis.typeCheckingMode` в значение `basic`. + +## Вложенные параметры + +Вложенные параметры — это словари, типизированные с помощью `TypedDict`, например: + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## Загрузка файлов + +Параметры запросов, соответствующие загрузке файлов, могут быть переданы как `bytes`, экземпляр [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) или кортеж `(filename, contents, media type)`. + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +Асинхронный клиент использует точно такой же интерфейс. Если вы передаёте экземпляр [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike), содержимое файла будет прочитано асинхронно автоматически. + +## Обработка ошибок + +Когда библиотека не может подключиться к API (например, из-за проблем с сетевым соединением или таймаута), выбрасывается подкласс `groq.APIConnectionError`. + +Когда API возвращает код статуса, отличный от успешного (то есть ответ 4xx или 5xx), выбрасывается подкласс `groq.APIStatusError`, содержащий свойства `status_code` и `response`. + +Все ошибки наследуются от `groq.APIError`. + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Коды ошибок следующие: + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### Повторные попытки + +Некоторые ошибки автоматически повторяются 2 раза по умолчанию с короткой экспоненциальной задержкой. Ошибки соединения (например, из-за проблем с сетевым подключением), 408 Request Timeout, 409 Conflict, 429 Rate Limit и внутренние ошибки >=500 по умолчанию повторяются. + +Вы можете использовать опцию `max_retries` для настройки или отключения параметров повторных попыток: + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### Таймауты + +По умолчанию запросы завершаются по таймауту через 1 минуту. Вы можете настроить это с помощью опции `timeout`, которая принимает float или объект [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration): + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +При таймауте выбрасывается `APITimeoutError`. + +Обратите внимание, что запросы, завершившиеся по таймауту, [повторяются дважды по умолчанию](#повторные-попытки). + +## Расширенные возможности + +### Логирование + +Мы используем модуль [`logging`](https://docs.python.org/3/library/logging.html) стандартной библиотеки. + +Вы можете включить логирование, установив переменную окружения `GROQ_LOG` в значение `info`. + +```shell +$ export GROQ_LOG=info +``` + +Или в значение `debug` для более подробного логирования. + +### Как определить, означает ли `None` значение `null` или отсутствие поля + +В ответе API поле может быть явно `null` или полностью отсутствовать; в обоих случаях его значение в этой библиотеке равно `None`. Вы можете различить эти два случая с помощью `.model_fields_set`: + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Доступ к необработанным данным ответа (например, заголовкам) + +«Необработанный» объект Response можно получить, добавив префикс `.with_raw_response.` к любому вызову HTTP-метода, например: + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +Эти методы возвращают объект [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py). + +Асинхронный клиент возвращает [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) с той же структурой; единственное отличие — методы с `await` для чтения содержимого ответа. + +#### `.with_streaming_response` + +Описанный выше интерфейс жадно считывает всё тело ответа при выполнении запроса, что не всегда желательно. + +Для потоковой передачи тела ответа используйте `.with_streaming_response`, что требует менеджера контекста и считывает тело ответа только после вызова `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` или `.parse()`. В асинхронном клиенте это асинхронные методы. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +Менеджер контекста необходим для надёжного закрытия ответа. + +### Выполнение пользовательских/недокументированных запросов + +Эта библиотека типизирована для удобного доступа к документированному API. + +Если вам нужен доступ к недокументированным эндпоинтам, параметрам или свойствам ответов, библиотекой всё равно можно пользоваться. + +#### Недокументированные эндпоинты + +Для выполнения запросов к недокументированным эндпоинтам вы можете использовать `client.get`, `client.post` и другие HTTP-глаголы. Параметры клиента (например, повторные попытки) будут учитываться при выполнении такого запроса. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Недокументированные параметры запросов + +Если вы хотите явно отправить дополнительный параметр, вы можете сделать это с помощью опций запроса `extra_query`, `extra_body` и `extra_headers`. + +#### Недокументированные свойства ответов + +Для доступа к недокументированным свойствам ответов вы можете обращаться к дополнительным полям, например `response.unknown_prop`. Вы также можете получить все дополнительные поля модели Pydantic в виде словаря с помощью [`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). + +### Настройка HTTP-клиента + +Вы можете напрямую переопределить [клиент httpx](https://www.python-httpx.org/api/#client) для настройки под ваш случай использования, включая: + +- Поддержку [прокси](https://www.python-httpx.org/advanced/proxies/) +- Пользовательские [транспорты](https://www.python-httpx.org/advanced/transports/) +- Дополнительные [расширенные](https://www.python-httpx.org/advanced/clients/) возможности + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +Вы также можете настраивать клиент для отдельных запросов с помощью `with_options()`: + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Управление HTTP-ресурсами + +По умолчанию библиотека закрывает базовые HTTP-соединения при [сборке мусора](https://docs.python.org/3/reference/datamodel.html#object.__del__) клиента. При необходимости вы можете вручную закрыть клиент с помощью метода `.close()` или использовать менеджер контекста, который закрывает соединение при выходе. + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Версионирование + +Этот пакет в целом следует соглашениям [SemVer](https://semver.org/spec/v2.0.0.html), хотя некоторые обратно несовместимые изменения могут выпускаться как минорные версии: + +1. Изменения, затрагивающие только статические типы, без нарушения поведения во время выполнения. +2. Изменения во внутренних компонентах библиотеки, которые технически являются публичными, но не предназначены или не документированы для внешнего использования. _(Пожалуйста, откройте issue на GitHub, если вы полагаетесь на такие внутренние компоненты.)_ +3. Изменения, которые, как мы ожидаем, не повлияют на подавляющее большинство пользователей на практике. + +Мы серьёзно относимся к обратной совместимости и стремимся обеспечить плавный процесс обновления. + +Мы будем рады вашей обратной связи; откройте [issue](https://www.github.com/groq/groq-python/issues) с вопросами, сообщениями об ошибках или предложениями. + +### Определение установленной версии + +Если вы обновились до последней версии, но не видите ожидаемых новых функций, вероятно, ваша среда Python всё ещё использует более старую версию. + +Вы можете определить версию, используемую во время выполнения, с помощью: + +```py +import groq +print(groq.__version__) +``` + +## Требования + +Python 3.10 или выше. + +## Участие в разработке + +См. [документацию по участию в разработке](./CONTRIBUTING.md). diff --git a/README-ZH.md b/README-ZH.md new file mode 100644 index 0000000..de92924 --- /dev/null +++ b/README-ZH.md @@ -0,0 +1,474 @@ +# Groq Python API 库 + +**语言 / Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + + +[![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/) + +Groq Python 库为任何 Python 3.10+ 应用程序提供了便捷访问 Groq REST API 的方式。该库包含所有请求参数和响应字段的类型定义，并提供由 [httpx](https://github.com/encode/httpx) 驱动的同步与异步客户端。 + +本库由 [Stainless](https://www.stainless.com/) 生成。 + +## 文档 + +REST API 文档可在 [console.groq.com](https://console.groq.com/docs) 查看。本库的完整 API 说明见 [api.md](api.md)。 + +## 安装 + +```sh +# install from PyPI +pip install groq +``` + +## 用法 + +本库的完整 API 说明见 [api.md](api.md)。 + +```python +import os +from groq import Groq + +client = Groq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + +chat_completion = client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", +) +print(chat_completion.choices[0].message.content) +``` + +虽然你可以通过 `api_key` 关键字参数传入 API 密钥，但我们建议使用 [python-dotenv](https://pypi.org/project/python-dotenv/) 将 `GROQ_API_KEY="My API Key"` 添加到 `.env` 文件中，这样 API 密钥就不会被提交到源代码管理中。 + +## 异步用法 + +只需导入 `AsyncGroq` 而不是 `Groq`，并在每次 API 调用时使用 `await`： + +```python +import os +import asyncio +from groq import AsyncGroq + +client = AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted +) + + +async def main() -> None: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.choices[0].message.content) + + +asyncio.run(main()) +``` + +同步客户端与异步客户端的功能在其他方面完全相同。 + +### 使用 aiohttp + +默认情况下，异步客户端使用 `httpx` 发起 HTTP 请求。不过，为提升并发性能，你也可以将 `aiohttp` 用作 HTTP 后端。 + +安装 `aiohttp` 即可启用： + +```sh +# install from PyPI +pip install groq[aiohttp] +``` + +然后通过使用 `http_client=DefaultAioHttpClient()` 实例化客户端来启用： + +```python +import os +import asyncio +from groq import DefaultAioHttpClient +from groq import AsyncGroq + + +async def main() -> None: + async with AsyncGroq( + api_key=os.environ.get("GROQ_API_KEY"), # This is the default and can be omitted + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + } + ], + model="openai/gpt-oss-20b", + ) + print(chat_completion.id) + + +asyncio.run(main()) +``` + +## 使用类型 + +嵌套请求参数为 [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict)。响应为 [Pydantic 模型](https://docs.pydantic.dev)，并提供如下辅助方法： + +- 序列化为 JSON：`model.to_json()` +- 转换为字典：`model.to_dict()` + +类型化的请求与响应可在编辑器中提供自动补全和文档。若希望在 VS Code 中尽早通过类型错误发现 bug，可将 `python.analysis.typeCheckingMode` 设置为 `basic`。 + +## 嵌套参数 + +嵌套参数为字典，使用 `TypedDict` 进行类型标注，例如： + +```python +from groq import Groq + +client = Groq() + +chat_completion = client.chat.completions.create( + messages=[ + { + "content": "string", + "role": "system", + } + ], + model="meta-llama/llama-4-scout-17b-16e-instruct", + compound_custom={}, +) +print(chat_completion.compound_custom) +``` + +## 文件上传 + +对应文件上传的请求参数可传入 `bytes`、[`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) 实例，或 `(filename, contents, media type)` 元组。 + +```python +from pathlib import Path +from groq import Groq + +client = Groq() + +client.audio.transcriptions.create( + model="whisper-large-v3-turbo", + file=Path("/path/to/file"), +) +``` + +异步客户端使用完全相同的接口。若传入 [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) 实例，文件内容将自动异步读取。 + +## 错误处理 + +当库无法连接到 API（例如因网络连接问题或超时）时，会抛出 `groq.APIConnectionError` 的子类。 + +当 API 返回非成功状态码（即 4xx 或 5xx 响应）时，会抛出 `groq.APIStatusError` 的子类，其中包含 `status_code` 和 `response` 属性。 + +所有错误均继承自 `groq.APIError`。 + +```python +import groq +from groq import Groq + +client = Groq() + +try: + client.chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", + ) +except groq.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except groq.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except groq.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +错误代码对应关系如下： + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +### 重试 + +某些错误默认会自动重试 2 次，并采用简短的指数退避。连接错误（例如网络连通性问题）、408 Request Timeout、409 Conflict、429 Rate Limit 以及 >=500 内部错误默认都会重试。 + +可使用 `max_retries` 选项配置或禁用重试设置： + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +### 超时 + +默认情况下，请求在 1 分钟后超时。可通过 `timeout` 选项进行配置，该选项接受浮点数或 [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) 对象： + +```python +from groq import Groq + +# Configure the default for all requests: +client = Groq( + # 20 seconds (default is 1 minute) + timeout=20.0, +) + +# More granular control: +client = Groq( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) +``` + +超时时会抛出 `APITimeoutError`。 + +请注意，超时的请求[默认会重试两次](#重试)。 + +## 高级用法 + +### 日志 + +我们使用标准库的 [`logging`](https://docs.python.org/3/library/logging.html) 模块。 + +将环境变量 `GROQ_LOG` 设置为 `info` 即可启用日志。 + +```shell +$ export GROQ_LOG=info +``` + +或设置为 `debug` 以获取更详细的日志。 + +### 如何判断 `None` 表示 `null` 还是缺失 + +在 API 响应中，字段可能显式为 `null`，或完全缺失；在这两种情况下，本库中的值均为 `None`。可通过 `.model_fields_set` 区分这两种情况： + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### 访问原始响应数据（例如 headers） + +可在任何 HTTP 方法调用前加上 `.with_raw_response.` 前缀来访问“原始” Response 对象，例如： + +```py +from groq import Groq + +client = Groq() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "system", + "content": "You are a helpful assistant.", + }, { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }], + model="openai/gpt-oss-20b", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion.id) +``` + +这些方法返回 [`APIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py) 对象。 + +异步客户端返回结构相同的 [`AsyncAPIResponse`](https://github.com/groq/groq-python/tree/main/src/groq/_response.py)，唯一区别是读取响应内容的方法需要 `await`。 + +#### `.with_streaming_response` + +上述接口在发起请求时会立即读取完整响应体，这可能并不总是你想要的。 + +若要流式读取响应体，请改用 `.with_streaming_response`，它需要上下文管理器，且只有在你调用 `.read()`、`.text()`、`.json()`、`.iter_bytes()`、`.iter_text()`、`.iter_lines()` 或 `.parse()` 时才会读取响应体。在异步客户端中，这些为异步方法。 + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "system", + "content": "You are a helpful assistant.", + }, + { + "role": "user", + "content": "Explain the importance of low latency LLMs", + }, + ], + model="openai/gpt-oss-20b", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +必须使用上下文管理器，以确保响应能被可靠关闭。 + +### 发起自定义/未文档化的请求 + +本库针对已文档化的 API 进行了类型标注，便于使用。 + +若需要访问未文档化的端点、参数或响应属性，仍可使用本库。 + +#### 未文档化的端点 + +要对未文档化的端点发起请求，可使用 `client.get`、`client.post` 及其他 HTTP 动词。发起请求时会尊重客户端上的选项（例如重试）。 + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### 未文档化的请求参数 + +若要显式发送额外参数，可使用 `extra_query`、`extra_body` 和 `extra_headers` 请求选项。 + +#### 未文档化的响应属性 + +要访问未文档化的响应属性，可像 `response.unknown_prop` 一样访问额外字段。也可通过 [`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra) 将 Pydantic 模型上的所有额外字段获取为字典。 + +### 配置 HTTP 客户端 + +可直接覆盖 [httpx 客户端](https://www.python-httpx.org/api/#client) 以根据你的用例进行自定义，包括： + +- 支持[代理](https://www.python-httpx.org/advanced/proxies/) +- 自定义[传输层](https://www.python-httpx.org/advanced/transports/) +- 其他[高级](https://www.python-httpx.org/advanced/clients/)功能 + +```python +import httpx +from groq import Groq, DefaultHttpxClient + +client = Groq( + # Or use the `GROQ_BASE_URL` env var + base_url="http://my.test.server.example.com:8083", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +也可通过 `with_options()` 在每次请求时自定义客户端： + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### 管理 HTTP 资源 + +默认情况下，当客户端被[垃圾回收](https://docs.python.org/3/reference/datamodel.html#object.__del__)时，库会关闭底层 HTTP 连接。如需手动关闭，可使用 `.close()` 方法，或使用在退出时自动关闭的上下文管理器。 + +```py +from groq import Groq + +with Groq() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## 版本管理 + +本包通常遵循 [SemVer](https://semver.org/spec/v2.0.0.html) 约定，但某些向后不兼容的变更可能作为次要版本发布： + +1. 仅影响静态类型、不破坏运行时行为的变更。 +2. 对库内部的技术上公开但未面向外部使用或文档化的变更。_（若你依赖此类内部实现，请提交 GitHub issue 告知我们。）_ +3. 我们预计在实践中不会影响绝大多数用户的变更。 + +我们高度重视向后兼容性，并努力确保你能获得顺畅的升级体验。 + +我们欢迎你的反馈；如有问题、bug 或建议，请提交 [issue](https://www.github.com/groq/groq-python/issues)。 + +### 确定已安装版本 + +若你已升级到最新版本却看不到预期的新功能，可能是 Python 环境仍在使用旧版本。 + +可在运行时通过以下方式确定正在使用的版本： + +```py +import groq +print(groq.__version__) +``` + +## 系统要求 + +Python 3.10 或更高版本。 + +## 贡献 + +请参阅[贡献文档](./CONTRIBUTING.md)。 diff --git a/README.md b/README.md index 3eea186..6071d39 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Groq Python API library +**Languages:** [English](./README.md) · [中文](./README-ZH.md) · [Español](./README-ES.md) · [Français](./README-FR.md) · [Português](./README-PT.md) · [Русский](./README-RU.md) · [Deutsch](./README-DE.md) + [![PyPI version](https://img.shields.io/pypi/v/groq.svg?label=pypi%20(stable))](https://pypi.org/project/groq/)