GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

openai/openai-python

Public

mirrored from https://github.com/openai/openai-pythonAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
v0.27.2

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

README.md

294lines · modeblame

RawDownload
Latest commit unavailable.
3c6d4cd6Greg Brockman5 years ago1# OpenAI Python Library
2
3The OpenAI Python library provides convenient access to the OpenAI API
4from applications written in the Python language. It includes a
5pre-defined set of classes for API resources that initialize
6themselves dynamically from API responses which makes it compatible
7with a wide range of versions of the OpenAI API.
8
bf51385aLogan Kilpatrick3 years ago9You can find usage examples for the OpenAI Python library in our [API reference](https://beta.openai.com/docs/api-reference?lang=python) and the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/).
3c6d4cd6Greg Brockman5 years ago10
11## Installation
12
13You don't need this source code unless you want to modify the package. If you just
14want to use the package, just run:
15
16```sh
17pip install --upgrade openai
18```
19
20Install from source with:
21
22```sh
23python setup.py install
24```
25
ede08829Jakub Roztocil3 years ago26### Optional dependencies
27
777c1c3dJosh Bode3 years ago28Install dependencies for [`openai.embeddings_utils`](openai/embeddings_utils.py):
ede08829Jakub Roztocil3 years ago29
30```sh
31pip install openai[embeddings]
32```
33
34Install support for [Weights & Biases](https://wandb.me/openai-docs):
35
36```
37pip install openai[wandb]
38```
39
40Data libraries like `numpy` and `pandas` are not installed by default due to their size. They’re needed for some functionality of this library, but generally not for talking to the API. If you encounter a `MissingDependencyError`, install them with:
41
42```sh
43pip install openai[datalib]
44````
45
d53d9efbRachel Lim5 years ago46## Usage
47
62b73b9bAtty Eleti3 years ago48The library needs to be configured with your account's secret key which is available on the [website](https://platform.openai.com/account/api-keys). Either set it as the `OPENAI_API_KEY` environment variable before using the library:
d53d9efbRachel Lim5 years ago49
50```bash
51export OPENAI_API_KEY='sk-...'
52```
53
54Or set `openai.api_key` to its value:
55
56```python
57import openai
58openai.api_key = "sk-..."
59
62b73b9bAtty Eleti3 years ago60# list models
61models = openai.Model.list()
d53d9efbRachel Lim5 years ago62
62b73b9bAtty Eleti3 years ago63# print the first model's id
64print(models.data[0].id)
d53d9efbRachel Lim5 years ago65
66# create a completion
62b73b9bAtty Eleti3 years ago67completion = openai.Completion.create(model="ada", prompt="Hello world")
d53d9efbRachel Lim5 years ago68
69# print the completion
70print(completion.choices[0].text)
71```
72
3edecbeehallacy3 years ago73
74### Params
4a33f3f1Agnieszka Stec3 years ago75All endpoints have a `.create` method that supports a `request_timeout` param. This param takes a `Union[float, Tuple[float, float]]` and will raise an `openai.error.TimeoutError` error if the request exceeds that time in seconds (See: https://requests.readthedocs.io/en/latest/user/quickstart/#timeouts).
3edecbeehallacy3 years ago76
f288b001Sorin Suciu4 years ago77### Microsoft Azure Endpoints
78
ec4943f9Christian Mürtz3 years ago79In order to use the library with Microsoft Azure endpoints, you need to set the `api_type`, `api_base` and `api_version` in addition to the `api_key`. The `api_type` must be set to 'azure' and the others correspond to the properties of your endpoint.
f288b001Sorin Suciu4 years ago80In addition, the deployment name must be passed as the engine parameter.
81
82```python
83import openai
84openai.api_type = "azure"
85openai.api_key = "..."
86openai.api_base = "https://example-endpoint.openai.azure.com"
ec4943f9Christian Mürtz3 years ago87openai.api_version = "2022-12-01"
f288b001Sorin Suciu4 years ago88
89# create a completion
53e5ba4bt-asutedjo4 years ago90completion = openai.Completion.create(engine="deployment-name", prompt="Hello world")
f288b001Sorin Suciu4 years ago91
92# print the completion
93print(completion.choices[0].text)
94```
62b51ca0Boris Dayma4 years ago95
ec4943f9Christian Mürtz3 years ago96Please note that for the moment, the Microsoft Azure endpoints can only be used for completion, embedding, and fine-tuning operations.
4a33f3f1Agnieszka Stec3 years ago97For a detailed example of how to use fine-tuning and other operations using Azure endpoints, please check out the following Jupyter notebooks:
ec4943f9Christian Mürtz3 years ago98* [Using Azure completions](https://github.com/openai/openai-cookbook/tree/main/examples/azure/completions.ipynb)
7884a7b9Ted Sanders3 years ago99* [Using Azure fine-tuning](https://github.com/openai/openai-cookbook/tree/main/examples/azure/finetuning.ipynb)
100* [Using Azure embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/azure/embeddings.ipynb)
f288b001Sorin Suciu4 years ago101
53e5ba4bt-asutedjo4 years ago102### Microsoft Azure Active Directory Authentication
103
ec4943f9Christian Mürtz3 years ago104In order to use Microsoft Active Directory to authenticate to your Azure endpoint, you need to set the `api_type` to "azure_ad" and pass the acquired credential token to `api_key`. The rest of the parameters need to be set as specified in the previous section.
53e5ba4bt-asutedjo4 years ago105
106
107```python
108from azure.identity import DefaultAzureCredential
109import openai
110
111# Request credential
112default_credential = DefaultAzureCredential()
ec4943f9Christian Mürtz3 years ago113token = default_credential.get_token("https://cognitiveservices.azure.com/.default")
53e5ba4bt-asutedjo4 years ago114
115# Setup parameters
116openai.api_type = "azure_ad"
117openai.api_key = token.token
118openai.api_base = "https://example-endpoint.openai.azure.com/"
ec4943f9Christian Mürtz3 years ago119openai.api_version = "2022-12-01"
53e5ba4bt-asutedjo4 years ago120
121# ...
122```
d53d9efbRachel Lim5 years ago123### Command-line interface
124
125This library additionally provides an `openai` command-line utility
126which makes it easy to interact with the API from your terminal. Run
127`openai api -h` for usage.
128
0e21703eTed Sanders4 years ago129```sh
62b73b9bAtty Eleti3 years ago130# list models
131openai api models.list
d53d9efbRachel Lim5 years ago132
133# create a completion
62b73b9bAtty Eleti3 years ago134openai api completions.create -m ada -p "Hello world"
135
136# create a chat completion
137openai api chat_completions.create -m gpt-3.5-turbo -g user "Hello world"
dc33cb9dMichelle Pokrass3 years ago138
139# generate images via DALL·E API
140openai api image.create -p "two dogs playing chess, cartoon" -n 1
d53d9efbRachel Lim5 years ago141```
142
0e21703eTed Sanders4 years ago143## Example code
144
7884a7b9Ted Sanders3 years ago145Examples of how to use this Python library to accomplish various tasks can be found in the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/). It contains code examples for:
146
147* Classification using fine-tuning
148* Clustering
149* Code search
150* Customizing embeddings
151* Question answering from a corpus of documents
152* Recommendations
153* Visualization of embeddings
154* And more
155
156Prior to July 2022, this OpenAI Python library hosted code examples in its examples folder, but since then all examples have been migrated to the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/).
0e21703eTed Sanders4 years ago157
62b73b9bAtty Eleti3 years ago158### Chat
159
160Conversational models such as `gpt-3.5-turbo` can be called using the chat completions endpoint.
161
162```python
163import openai
164openai.api_key = "sk-..." # supply your API key however you choose
165
166completion = openai.ChatCompletion.create(model="gpt-3.5-turbo", messages=[{"role": "user", "content": "Hello world!"}])
167print(completion.choices[0].message.content)
168```
169
0e21703eTed Sanders4 years ago170### Embeddings
171
172In the OpenAI Python library, an embedding represents a text string as a fixed-length vector of floating point numbers. Embeddings are designed to measure the similarity or relevance between text strings.
173
174To get an embedding for a text string, you can use the embeddings method as follows in Python:
175
176```python
177import openai
178openai.api_key = "sk-..." # supply your API key however you choose
179
180# choose text to embed
181text_string = "sample text"
182
183# choose an embedding
f4be8f2fhallacy4 years ago184model_id = "text-similarity-davinci-001"
0e21703eTed Sanders4 years ago185
186# compute the embedding of the text
62b73b9bAtty Eleti3 years ago187embedding = openai.Embedding.create(input=text_string, model=model_id)['data'][0]['embedding']
0e21703eTed Sanders4 years ago188```
189
7884a7b9Ted Sanders3 years ago190An example of how to call the embeddings method is shown in this [get embeddings notebook](https://github.com/openai/openai-cookbook/blob/main/examples/Get_embeddings.ipynb).
0e21703eTed Sanders4 years ago191
192Examples of how to use embeddings are shared in the following Jupyter notebooks:
193
7884a7b9Ted Sanders3 years ago194- [Classification using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Classification_using_embeddings.ipynb)
195- [Clustering using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Clustering.ipynb)
196- [Code search using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Code_search.ipynb)
197- [Semantic text search using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Semantic_text_search_using_embeddings.ipynb)
198- [User and product embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/User_and_product_embeddings.ipynb)
199- [Zero-shot classification using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Zero-shot_classification_with_embeddings.ipynb)
200- [Recommendation using embeddings](https://github.com/openai/openai-cookbook/blob/main/examples/Recommendation_using_embeddings.ipynb)
0e21703eTed Sanders4 years ago201
202For more information on embeddings and the types of embeddings OpenAI offers, read the [embeddings guide](https://beta.openai.com/docs/guides/embeddings) in the OpenAI documentation.
203
4a33f3f1Agnieszka Stec3 years ago204### Fine-tuning
0e21703eTed Sanders4 years ago205
4a33f3f1Agnieszka Stec3 years ago206Fine-tuning a model on training data can both improve the results (by giving the model more examples to learn from) and reduce the cost/latency of API calls (chiefly through reducing the need to include training examples in prompts).
0e21703eTed Sanders4 years ago207
4a33f3f1Agnieszka Stec3 years ago208Examples of fine-tuning are shared in the following Jupyter notebooks:
0e21703eTed Sanders4 years ago209
4a33f3f1Agnieszka Stec3 years ago210- [Classification with fine-tuning](https://github.com/openai/openai-cookbook/blob/main/examples/Fine-tuned_classification.ipynb) (a simple notebook that shows the steps required for fine-tuning)
211- Fine-tuning a model that answers questions about the 2020 Olympics
7884a7b9Ted Sanders3 years ago212- [Step 1: Collecting data](https://github.com/openai/openai-cookbook/blob/main/examples/fine-tuned_qa/olympics-1-collect-data.ipynb)
213- [Step 2: Creating a synthetic Q&A dataset](https://github.com/openai/openai-cookbook/blob/main/examples/fine-tuned_qa/olympics-2-create-qa.ipynb)
214- [Step 3: Train a fine-tuning model specialized for Q&A](https://github.com/openai/openai-cookbook/blob/main/examples/fine-tuned_qa/olympics-3-train-qa.ipynb)
0e21703eTed Sanders4 years ago215
62b51ca0Boris Dayma4 years ago216Sync your fine-tunes to [Weights & Biases](https://wandb.me/openai-docs) to track experiments, models, and datasets in your central dashboard with:
217
218```bash
219openai wandb sync
220```
221
4a33f3f1Agnieszka Stec3 years ago222For more information on fine-tuning, read the [fine-tuning guide](https://beta.openai.com/docs/guides/fine-tuning) in the OpenAI documentation.
0e21703eTed Sanders4 years ago223
3c00e856hallacy3 years ago224### Moderation
225
62b73b9bAtty Eleti3 years ago226OpenAI provides a Moderation endpoint that can be used to check whether content complies with the OpenAI [content policy](https://platform.openai.com/docs/usage-policies)
3c00e856hallacy3 years ago227
228```python
229import openai
230openai.api_key = "sk-..." # supply your API key however you choose
231
232moderation_resp = openai.Moderation.create(input="Here is some perfectly innocuous text that follows all OpenAI content policies.")
233```
234
62b73b9bAtty Eleti3 years ago235See the [moderation guide](https://platform.openai.com/docs/guides/moderation) for more details.
3c00e856hallacy3 years ago236
dc33cb9dMichelle Pokrass3 years ago237## Image generation (DALL·E)
238
239```python
240import openai
241openai.api_key = "sk-..." # supply your API key however you choose
242
243image_resp = openai.Image.create(prompt="two dogs playing chess, oil painting", n=4, size="512x512")
244
245```
246
62b73b9bAtty Eleti3 years ago247## Audio transcription (Whisper)
248```python
249import openai
250openai.api_key = "sk-..." # supply your API key however you choose
251f = open("path/to/file.mp3", "rb")
252transcript = openai.Audio.transcribe("whisper-1", f)
253
254```
255
0abf6413Andrew Chen Wang3 years ago256## Async API
257
258Async support is available in the API by prepending `a` to a network-bound method:
259
260```python
261import openai
262openai.api_key = "sk-..." # supply your API key however you choose
263
264async def create_completion():
62b73b9bAtty Eleti3 years ago265completion_resp = await openai.Completion.acreate(prompt="This is a test", model="davinci")
0abf6413Andrew Chen Wang3 years ago266
267```
268
269To make async requests more efficient, you can pass in your own
270``aiohttp.ClientSession``, but you must manually close the client session at the end
271of your program/event loop:
272
273```python
274import openai
275from aiohttp import ClientSession
276
277openai.aiosession.set(ClientSession())
278# At the end of your program, close the http session
279await openai.aiosession.get().close()
280```
281
62b73b9bAtty Eleti3 years ago282See the [usage guide](https://platform.openai.com/docs/guides/images) for more details.
dc33cb9dMichelle Pokrass3 years ago283
3c6d4cd6Greg Brockman5 years ago284## Requirements
285
62f8d40fMadeleine Thompson4 years ago286- Python 3.7.1+
3c6d4cd6Greg Brockman5 years ago287
34a12097Chris3 years ago288In general, we want to support the versions of Python that our
289customers are using. If you run into problems with any version
fb6232f7Logan Kilpatrick3 years ago290issues, please let us know at on our [support page](https://help.openai.com/en/).
3c6d4cd6Greg Brockman5 years ago291
292## Credit
293
294This library is forked from the [Stripe Python Library](https://github.com/stripe/stripe-python).