# Search with embeddings

Find the passages of your own documents that answer a question, then answer from them.

1. [Cut your documents into passages](#1-cut-your-documents-into-passages).
2. [Turn passages and question into vectors](#2-turn-passages-and-question-into-vectors).
3. [Rank the passages](#3-rank-the-passages).
4. [Answer from the best passages](#4-answer-from-the-best-passages).

Yacine's Souk Bot answers the customers of a clothing shop in Oran. Its answers about delivery, payment and returns must come from the shop's own rules, not from what a model guesses.

## 1. Cut your documents into passages

A passage is the piece of text a search returns: one idea, a paragraph or a few.

| Rule | Why |
|---|---|
| cut at paragraphs and headings, not at a fixed length | a passage holds one whole idea |
| repeat the last sentence of a passage at the start of the next | an answer that spans two passages is still found |
| keep the source beside each passage | the answer can say where it comes from |

## 2. Turn passages and question into vectors

Send the passages to `/v1/embeddings` once, with `input_type: "search_document"`, and store each vector beside its passage: a file, or a database that searches vectors. Each question then goes to the same route with `input_type: "search_query"`. How the route works: [Embeddings](/docs/embeddings).

The sample does steps 2 and 3 in one run: it sends the passages, then the question, and prints the two passages closest to it.

```python
import json
import math
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/embeddings"
MODEL = "voyageai/voyage-multimodal-3.5"
QUESTION = "Vous livrez à Constantine ?"

passages = [
    "Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
    "Paiement à la livraison, ou par carte Edahabia ou CIB.",
    "Retour accepté sous 7 jours, article non porté.",
    "Boutique ouverte du samedi au jeudi, de 9 h à 19 h.",
]


def embed(texts, input_type):
    request = urllib.request.Request(
        ADDRESS,
        data=json.dumps(
            {
                "model": MODEL,
                "input": texts,
                "input_type": input_type,
            }
        ).encode(),
        headers={
            "Authorization": "Bearer " + API_KEY,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request) as response:
        answer = json.load(response)
    return [item["embedding"] for item in answer["data"]]


def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    return dot / (math.hypot(*a) * math.hypot(*b))


index = embed(passages, "search_document")
query = embed([QUESTION], "search_query")[0]

scores = [cosine(query, vector) for vector in index]
ranked = sorted(zip(scores, passages), reverse=True)
for score, text in ranked[:2]:
    print(round(score, 3), text)
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/embeddings";
const MODEL = "voyageai/voyage-multimodal-3.5";
const QUESTION = "Vous livrez à Constantine ?";

const passages = [
  "Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
  "Paiement à la livraison, ou par carte Edahabia ou CIB.",
  "Retour accepté sous 7 jours, article non porté.",
  "Boutique ouverte du samedi au jeudi, de 9 h à 19 h.",
];

async function embed(texts, inputType) {
  const response = await fetch(ADDRESS, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: MODEL,
      input: texts,
      input_type: inputType,
    }),
  });
  const answer = await response.json();
  return answer.data.map((item) => item.embedding);
}

function cosine(a, b) {
  let dot = 0;
  let na = 0;
  let nb = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    na += a[i] * a[i];
    nb += b[i] * b[i];
  }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

const index = await embed(passages, "search_document");
const [query] = await embed([QUESTION], "search_query");

const ranked = passages
  .map((text, i) => ({ text, score: cosine(query, index[i]) }))
  .sort((a, b) => b.score - a.score);
for (const hit of ranked.slice(0, 2)) {
  console.log(hit.score.toFixed(3), hit.text);
}
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"math"
	"net/http"
	"os"
	"sort"
)

const (
	address  = "https://opendunes.com/v1/embeddings"
	model    = "voyageai/voyage-multimodal-3.5"
	question = "Vous livrez à Constantine ?"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	passages := []string{
		"Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
		"Paiement à la livraison, ou par carte Edahabia ou CIB.",
		"Retour accepté sous 7 jours, article non porté.",
		"Boutique ouverte du samedi au jeudi, de 9 h à 19 h.",
	}

	index := embed(apiKey, passages, "search_document")
	query := embed(apiKey, []string{question}, "search_query")[0]

	type hit struct {
		text  string
		score float64
	}
	hits := make([]hit, len(passages))
	for i, text := range passages {
		hits[i] = hit{text, cosine(query, index[i])}
	}
	sort.Slice(hits, func(a, b int) bool {
		return hits[a].score > hits[b].score
	})
	for _, h := range hits[:2] {
		fmt.Printf("%.3f %s\n", h.score, h.text)
	}
}

func embed(apiKey string, texts []string, inputType string) [][]float64 {
	body, err := json.Marshal(map[string]any{
		"model":      model,
		"input":      texts,
		"input_type": inputType,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Data []struct {
			Embedding []float64 `json:"embedding"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	vectors := make([][]float64, len(answer.Data))
	for i, item := range answer.Data {
		vectors[i] = item.Embedding
	}
	return vectors
}

func cosine(a, b []float64) float64 {
	var dot, na, nb float64
	for i := range a {
		dot += a[i] * b[i]
		na += a[i] * a[i]
		nb += b[i] * b[i]
	}
	return dot / (math.Sqrt(na) * math.Sqrt(nb))
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/embeddings"
MODEL="voyageai/voyage-multimodal-3.5"
QUESTION="Vous livrez à Constantine ?"

# The passages, once: one vector each, in the order sent
curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input_type": "search_document",
    "input": [
      "Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
      "Paiement à la livraison, ou par carte Edahabia ou CIB.",
      "Retour accepté sous 7 jours, article non porté.",
      "Boutique ouverte du samedi au jeudi, de 9 h à 19 h."
    ]
  }'

# The question: one vector, to compare with each passage
curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input_type": "search_query",
    "input": ["'"$QUESTION"'"]
  }'
```

<div class="dont">
<p>Store the passages' vectors from one model and search them with another. Vectors from two models do not compare.</p>
</div>

<div class="do">
<p>Send the passages and every question through the same <code>model</code>. A new model means sending every passage again.</p>
</div>

## 3. Rank the passages

Two vectors that point the same way hold texts that mean the same. Their cosine measures it: close to 1 for the same meaning, lower as meanings part. The samples score every passage against the question and keep the two highest. Illustrative: the scores depend on the model.

```text
0.612 Livraison partout en Algérie, sous 2 à 5 jours ouvrables.
0.431 Paiement à la livraison, ou par carte Edahabia ou CIB.
```

Keep the passages that score well above the rest; how many depends on their length and on the room in your prompt. Where a search returns many candidates, a rerank model can reorder them before the answer: see [Rerank](/docs/rerank).

## 4. Answer from the best passages

Send the passages and the question to a text model, with a rule: answer from these passages only, and say so when they do not hold the answer. The samples carry the two passages the search found.

```python
import os
from openai import OpenAI

API_KEY = os.environ["OPENDUNES_API_KEY"]
BASE_URL = "https://opendunes.com/v1"
MODEL = "anthropic/claude-sonnet-4.5"
QUESTION = "Vous livrez à Constantine ?"
RULE = "Answer from these passages only. If they lack it, say so."

passages = [
    "Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
    "Paiement à la livraison, ou par carte Edahabia ou CIB.",
]

client = OpenAI(base_url=BASE_URL, api_key=API_KEY)

system = RULE + "\n" + "\n".join("- " + p for p in passages)
reply = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": system},
        {"role": "user", "content": QUESTION},
    ],
)

print(reply.choices[0].message.content)
print(reply.usage.cost)
```

```javascript
import OpenAI from "openai";

const API_KEY = process.env.OPENDUNES_API_KEY;
const BASE_URL = "https://opendunes.com/v1";
const MODEL = "anthropic/claude-sonnet-4.5";
const QUESTION = "Vous livrez à Constantine ?";
const RULE = "Answer from these passages only. If they lack it, say so.";

const passages = [
  "Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
  "Paiement à la livraison, ou par carte Edahabia ou CIB.",
];

const client = new OpenAI({ baseURL: BASE_URL, apiKey: API_KEY });

const system = [RULE, ...passages.map((p) => `- ${p}`)].join("\n");
const reply = await client.chat.completions.create({
  model: MODEL,
  messages: [
    { role: "system", content: system },
    { role: "user", content: QUESTION },
  ],
});

console.log(reply.choices[0].message.content);
console.log(reply.usage.cost);
```

```go
package main

import (
	"context"
	"fmt"
	"os"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

const (
	baseURL  = "https://opendunes.com/v1"
	model    = "anthropic/claude-sonnet-4.5"
	question = "Vous livrez à Constantine ?"
	rule     = "Answer from these passages only. If they lack it, say so."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	passages := []string{
		"Livraison partout en Algérie, sous 2 à 5 jours ouvrables.",
		"Paiement à la livraison, ou par carte Edahabia ou CIB.",
	}

	client := openai.NewClient(
		option.WithBaseURL(baseURL),
		option.WithAPIKey(apiKey),
	)

	system := rule + "\n- " + strings.Join(passages, "\n- ")
	params := openai.ChatCompletionNewParams{
		Model: model,
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.SystemMessage(system),
			openai.UserMessage(question),
		},
	}
	reply, err := client.Chat.Completions.New(context.TODO(), params)
	if err != nil {
		panic(err)
	}

	fmt.Println(reply.Choices[0].Message.Content)
	fmt.Println(reply.Usage.RawJSON())
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
QUESTION="Vous livrez à Constantine ?"
RULE="Answer from these passages only. If they lack it, say so."
PASSAGE_1="Livraison partout en Algérie, sous 2 à 5 jours ouvrables."
PASSAGE_2="Paiement à la livraison, ou par carte Edahabia ou CIB."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "system",
        "content": "'"$RULE"' - '"$PASSAGE_1"' - '"$PASSAGE_2"'"
      },
      {
        "role": "user",
        "content": "'"$QUESTION"'"
      }
    ]
  }'
```

<div class="good-to-know">
<p>A question no passage answers gets "I don't know" from the rule, not a guess. Log those questions: they show what your documents are missing.</p>
</div>

## What it cost

Each request is charged in DA from your balance, and `usage.cost` on each answer gives it. Sending the passages is charged once, on the tokens sent; each question then costs one short vectors request and one text answer. The model's page in *Models* gives each rate. Every field of both routes: [Vectors](/docs/reference/embeddings) · [Chat](/docs/reference/chat-completions).
