0
# Models
1
2
Model listing and information retrieval for discovering available models and their capabilities. Provides access to model metadata, supported features, and configuration options for selecting the appropriate model for specific use cases.
3
4
## Capabilities
5
6
### Model Listing
7
8
Retrieve a list of all available models with their basic information and capabilities.
9
10
```python { .api }
11
def list(
12
self,
13
*,
14
cf_ray: str | NotGiven = NOT_GIVEN,
15
x_amz_cf_id: str | NotGiven = NOT_GIVEN,
16
extra_headers: Headers | None = None,
17
extra_query: Query | None = None,
18
extra_body: Body | None = None,
19
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
20
) -> ModelListResponse:
21
"""
22
List available models.
23
24
Returns information about all models available through the Cerebras Cloud API,
25
including model IDs, capabilities, and basic metadata.
26
27
Parameters:
28
- cf_ray: CloudFlare Ray ID for request tracing
29
- x_amz_cf_id: Amazon CloudFront ID for request tracing
30
- extra_headers: Additional headers to include with the request
31
- extra_query: Additional query parameters
32
- extra_body: Additional request body data
33
- timeout: Request timeout override
34
35
Returns:
36
ModelListResponse containing list of available models
37
"""
38
```
39
40
### Model Retrieval
41
42
Get detailed information about a specific model including its capabilities, parameters, and configuration options.
43
44
```python { .api }
45
def retrieve(
46
self,
47
model_id: str,
48
*,
49
cf_ray: str | NotGiven = NOT_GIVEN,
50
x_amz_cf_id: str | NotGiven = NOT_GIVEN,
51
# Use the following arguments if you need to pass additional parameters to the API
52
extra_headers: Headers | None = None,
53
extra_query: Query | None = None,
54
extra_body: Body | None = None,
55
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
56
) -> ModelRetrieveResponse:
57
"""
58
Retrieve detailed information about a specific model.
59
60
Parameters:
61
- model_id: The ID of the model to retrieve (e.g., "llama3.1-70b")
62
- cf_ray: CloudFlare Ray ID for request tracing
63
- x_amz_cf_id: Amazon CloudFront ID for request tracing
64
- extra_headers: Additional headers to include with the request
65
- extra_query: Additional query parameters
66
- extra_body: Additional request body data
67
- timeout: Request timeout override
68
69
Returns:
70
ModelRetrieveResponse with detailed model information
71
"""
72
```
73
74
### Resource Classes
75
76
Synchronous and asynchronous resource classes that provide the models API methods.
77
78
```python { .api }
79
class ModelsResource(SyncAPIResource):
80
"""Synchronous models resource."""
81
82
@cached_property
83
def with_raw_response(self) -> ModelsResourceWithRawResponse: ...
84
85
@cached_property
86
def with_streaming_response(self) -> ModelsResourceWithStreamingResponse: ...
87
88
class AsyncModelsResource(AsyncAPIResource):
89
"""Asynchronous models resource."""
90
91
@cached_property
92
def with_raw_response(self) -> AsyncModelsResourceWithRawResponse: ...
93
94
@cached_property
95
def with_streaming_response(self) -> AsyncModelsResourceWithStreamingResponse: ...
96
```
97
98
## Response Types
99
100
### Model List Response
101
102
```python { .api }
103
class ModelListResponse(BaseModel):
104
"""Response containing list of available models."""
105
data: List[Model]
106
object: Literal["list"]
107
108
class Model(BaseModel):
109
"""Individual model information in list response."""
110
id: str
111
created: int
112
object: Literal["model"]
113
owned_by: str
114
```
115
116
### Model Retrieve Response
117
118
```python { .api }
119
class ModelRetrieveResponse(BaseModel):
120
"""Detailed information about a specific model."""
121
id: str
122
created: int
123
object: Literal["model"]
124
owned_by: str
125
# Additional model-specific metadata may be included
126
```
127
128
## Usage Examples
129
130
### List All Available Models
131
132
```python
133
from cerebras.cloud.sdk import Cerebras
134
135
client = Cerebras()
136
137
# Get list of all available models
138
models = client.models.list()
139
140
print("Available models:")
141
for model in models.data:
142
print(f"- {model.id} (owned by: {model.owned_by})")
143
```
144
145
### Retrieve Specific Model Information
146
147
```python
148
from cerebras.cloud.sdk import Cerebras
149
150
client = Cerebras()
151
152
# Get detailed information about a specific model
153
model_info = client.models.retrieve("llama3.1-70b")
154
155
print(f"Model ID: {model_info.id}")
156
print(f"Created: {model_info.created}")
157
print(f"Owned by: {model_info.owned_by}")
158
```
159
160
### Model Selection Logic
161
162
```python
163
from cerebras.cloud.sdk import Cerebras
164
165
def select_best_model(client: Cerebras, task_type: str) -> str:
166
"""
167
Select the most appropriate model for a given task type.
168
169
Args:
170
client: Cerebras client instance
171
task_type: Type of task ('chat', 'completion', 'code', etc.)
172
173
Returns:
174
Model ID string
175
"""
176
models = client.models.list()
177
178
# Simple model selection logic based on model ID patterns
179
model_ids = [model.id for model in models.data]
180
181
if task_type == "chat":
182
# Prefer larger models for chat tasks
183
for model_id in model_ids:
184
if "70b" in model_id.lower():
185
return model_id
186
elif task_type == "code":
187
# Look for code-specific models
188
for model_id in model_ids:
189
if "code" in model_id.lower():
190
return model_id
191
192
# Default to first available model
193
return model_ids[0] if model_ids else "llama3.1-70b"
194
195
# Usage
196
client = Cerebras()
197
best_model = select_best_model(client, "chat")
198
print(f"Selected model: {best_model}")
199
200
# Use the selected model
201
response = client.chat.completions.create(
202
model=best_model,
203
messages=[{"role": "user", "content": "Hello!"}]
204
)
205
```
206
207
### Async Model Operations
208
209
```python
210
import asyncio
211
from cerebras.cloud.sdk import AsyncCerebras
212
213
async def get_model_info():
214
client = AsyncCerebras()
215
216
# List models asynchronously
217
models = await client.models.list()
218
print(f"Found {len(models.data)} models")
219
220
# Get details for the first model
221
if models.data:
222
first_model = models.data[0]
223
details = await client.models.retrieve(first_model.id)
224
print(f"First model: {details.id}")
225
226
await client.aclose()
227
228
asyncio.run(get_model_info())
229
```
230
231
### Error Handling for Model Operations
232
233
```python
234
from cerebras.cloud.sdk import Cerebras, NotFoundError, APIError
235
236
client = Cerebras()
237
238
try:
239
# Try to retrieve a model that might not exist
240
model = client.models.retrieve("nonexistent-model")
241
print(f"Model found: {model.id}")
242
except NotFoundError:
243
print("Model not found")
244
# Fallback to listing available models
245
models = client.models.list()
246
print("Available models:")
247
for model in models.data:
248
print(f"- {model.id}")
249
except APIError as e:
250
print(f"API error: {e}")
251
```
252
253
### Model Metadata Analysis
254
255
```python
256
from cerebras.cloud.sdk import Cerebras
257
from datetime import datetime
258
259
client = Cerebras()
260
261
def analyze_models():
262
"""Analyze available models and their metadata."""
263
models = client.models.list()
264
265
print(f"Total models: {len(models.data)}")
266
267
# Group by owner
268
owners = {}
269
for model in models.data:
270
owner = model.owned_by
271
if owner not in owners:
272
owners[owner] = []
273
owners[owner].append(model.id)
274
275
print("\nModels by owner:")
276
for owner, model_ids in owners.items():
277
print(f" {owner}: {len(model_ids)} models")
278
for model_id in sorted(model_ids):
279
print(f" - {model_id}")
280
281
# Show creation dates
282
print("\nModel creation dates:")
283
for model in sorted(models.data, key=lambda m: m.created):
284
created_date = datetime.fromtimestamp(model.created)
285
print(f" {model.id}: {created_date.strftime('%Y-%m-%d %H:%M:%S')}")
286
287
analyze_models()
288
```