The Assistants API enables the creation of AI assistants integrated into your applications. These assistants possess instructions and utilize models, tools, and knowledge to address user queries. Presently, the Assistants API supports three categories of tools: Code Interpreter, Retrieval, and Function calling. The plans for the future include introducing additional tools developed by OpenAI and providing you the flexibility to contribute your tools to the platform.
In this tutorial, we will show you how to create Retrieval Assistants using the Python SDK. Before you start coding, we strongly recommend getting familiar with the Assistants using the Assistants playground.
We will provide you with an example of how you can upload a document, in this case the Alice’s Adventures in Wonderland, and you can ask questions about it.
Upload a File
The first thing that we have to do is to upload the document to OpenAI. Keep in mind that there are specific file formats that are supported for Code Interpreter and Retrieval respectively. In our example, we will work with a .txt file. Let’s start by uploading the pg11.txt file.
from openai import OpenAI
client = OpenAI()
client.files.create(
file=open("pg11.txt", "rb"),
purpose="assistants"
)
Output:
FileObject(id='file-EHecPBv4ByP4BcEYjV5U5tbG', bytes=174392,
created_at=1706711564, filename='pg11.txt', object='file',
purpose='assistants', status='processed', status_details=None)If we want to get a list of the uploaded files, we can run:
client.files.list()
Create an Assistant
The next step is to create an Assistant. Feel free to read the API Documentation for more information about the parameters.
my_assistant = client.beta.assistants.create(
instructions="You have read the document. When asked a question, write the response",
name="Alice Adventure's in Wonderland",
tools=[{"type": "retrieval"}],
model="gpt-4-turbo-preview",
)
print(my_assistant)
Output:
Assistant(id='asst_LlGIQbX6g7YuZDUiFt4dmP2B', created_at=1706712560, description=None, file_ids=[], instructions='You have read the document. When asked a question, write the response', metadata={}, model='gpt-4-turbo-preview', name="Alice Adventure's in Wonderland", object='assistant', tools=[ToolRetrieval(type='retrieval')])Create an Assistant File
At this point, we will create an assistant file by attaching the above file to the assistant file that we created earlier. We need to have the assistant_id and the file_id of assistant and the uploaded file respectively.
assistant_file = client.beta.assistants.files.create( assistant_id="asst_LlGIQbX6g7YuZDUiFt4dmP2B", file_id="file-EHecPBv4ByP4BcEYjV5U5tbG" ) print(assistant_file)
Output:
AssistantFile(id='file-EHecPBv4ByP4BcEYjV5U5tbG',
assistant_id='asst_LlGIQbX6g7YuZDUiFt4dmP2B',
created_at=1706713485, object='assistant.file')Create a Thread
The next step is to create a thread that represents a conversation.
thread = client.beta.threads.create() print(thread)
Output:
Thread(id='thread_qWHVDTQosNtQzjUkacGSVBjl', created_at=1706714300, metadata={}, object='thread')Add a Message to a Thread
A message includes text and, if permitted, can also include files uploaded by the user.
message = client.beta.threads.messages.create(
thread_id="thread_qWHVDTQosNtQzjUkacGSVBjl",
role="user",
content="What is the title of the book"
)
What is the title of the book
Run the Assistant
To generate a response from the Assistant based on the user’s message, you must initiate a Run. This prompts the Assistant to review the Thread, determining whether to activate tools (if enabled) or rely solely on the model for the most suitable response. Throughout the run’s progression, the Assistant adds Messages to the thread with the role=”assistant.” Additionally, the Assistant autonomously determines which previous Messages to include in the context window for the model, influencing both pricing and model performance. The current methodology has been fine-tuned using insights from ChatGPT’s development and may undergo further refinement in the future.
run = client.beta.threads.runs.create( thread_id="thread_qWHVDTQosNtQzjUkacGSVBjl", assistant_id="asst_LlGIQbX6g7YuZDUiFt4dmP2B" )
Get the Assistant’s Respond
Once the run completes, we can list the Messages added to the Thread by the Assistant.
messages = client.beta.threads.messages.list( thread_id="thread_qWHVDTQosNtQzjUkacGSVBjl" ) print(messages.data[0].content[0].dict()['text']['value'])
Output:
The title of the book is "Alice's Adventures in Wonderland" by Lewis Carroll【5†source】.Let’s ask the model a more complicated question, such as:
Who are the main characters of the book
message = client.beta.threads.messages.create(
thread_id="thread_qWHVDTQosNtQzjUkacGSVBjl",
role="user",
content="Who are the main characters of the book"
)
run = client.beta.threads.runs.create(
thread_id="thread_qWHVDTQosNtQzjUkacGSVBjl",
assistant_id="asst_LlGIQbX6g7YuZDUiFt4dmP2B"
)
messages = client.beta.threads.messages.list(
thread_id="thread_MokKoddKQ4V4LfWsI1VPUbXS"
)
print(messages.data[0].content[0].dict()['text']['value'])
Output:
The main characters of the book “Alice’s Adventures in Wonderland” include:
1. Alice – the young protagonist of the story who falls down a rabbit hole into a fantasy world called Wonderland.
2. The White Rabbit – a hurried and fretful creature that Alice follows down the rabbit hole.
3. The Queen of Hearts – a tyrannical ruler of Wonderland, notorious for her temper and her frequent decrees of death sentences.
4. The Cheshire Cat – known for its distinctive mischievous grin and its ability to appear and disappear at will.
5. The Mad Hatter – a tea-party host with a fondness for riddles and nonsense.
6. The March Hare – a companion of the Mad Hatter, equally nonsensical.
7. The Dormouse – another participant in the Mad Hatter’s tea party, often falling asleep during conversation.
8. The Caterpillar – a contemplative and somewhat cryptic character who speaks in riddles.
These characters, among others, play significant roles in Alice’s journey through Wonderland.
Delete the Files and the Assistants
You can delete a file by running the following command:
client.files.delete("file-EHecPBv4ByP4BcEYjV5U5tbG")
Finally, you can delete the assistant by running:
client.beta.assistants.delete("asst_LlGIQbX6g7YuZDUiFt4dmP2B")
Key Takeaways
With Assistants OpenAI we can work with Retrieval Augmented Generation (RAG) approaches which are quite popular and have many implementations, especially in the customer support sector. An alternative to the Assistants OpenAI is the LlamaIndex and the Langchain.
