chat completions embeddings tool use api

Here’s a quick overview of Chat Completions, Embeddings, and Tool Use in an API context:

1) Chat Completions API

Use this when you want a model to generate conversational or task-oriented text.

Typical uses:

• Q&A
• Summarization
• Drafting text
• Multi-turn conversation
• Reasoning over provided context

Example request shape:

{
  "model": "gpt-4.1-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Write a short email asking for a meeting."}
  ]
}

---

2) Embeddings API

Use this when you want to convert text into vectors for similarity search, clustering, classification, or retrieval.

Typical uses:

• Semantic search
• RAG (retrieval-augmented generation)
• Deduplication
• Recommendation
• Document clustering

Example request shape:

{
  "model": "text-embedding-3-small",
  "input": ["Hello world", "How are you?"]
}

Output: a vector for each input string.

---

3) Tool Use (Function Calling)

Use this when the model needs to call external functions or APIs to get information or perform actions.

Typical uses:

• Query a database
• Check weather
• Search internal docs
• Create calendar events
• Execute business logic

How it works:

1. You define tools/functions.
2. The model decides when to call them.
3. Your app executes the tool.
4. You send the result back to the model.
5. The model responds to the user.

Example tool definition:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {"type": "string"}
      },
      "required": ["city"]
    }
  }
}

Example flow:

• User: “What’s the weather in Paris?”
• Model: calls get_weather({"city":"Paris"})
• App: returns weather data
• Model: “It’s 18°C and sunny in Paris.”

---

When to use which

• Chat Completions: generate language
• Embeddings: search/compare text
• Tool Use: interact with external systems

---

Common pattern: RAG

A very common architecture is:

1. Convert documents to embeddings
2. Store vectors in a vector database
3. Embed user query
4. Retrieve relevant docs
5. Pass retrieved text to chat completions
6. Optionally use tools for live data/actions

---

If you want, I can also give you:

1. Python examples
2. JavaScript examples
3. A single end-to-end RAG + tool-calling example