Embeddings

What You’ll Build

A .prompty file that generates text embeddings — dense float vectors that capture semantic meaning. Use them for similarity search, retrieval augmented generation (RAG), clustering, or classification.

---

Step 1: Create an Embedding Prompt

Set apiType: embedding in the model block. The template body becomes the default text to embed, but you’ll typically pass text as an input:

embed.prompty

---
name: text-embedder
description: Generate embeddings for text input
model:
  id: text-embedding-3-small
  provider: openai
  apiType: embedding
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
inputs:
  - name: text
    kind: string
    default: Hello, world!
---
{{text}}

Note

For embeddings, the template body is the raw text to embed — no role markers (system:, user:) are needed. The parser produces a single message whose content is sent to the embeddings API.

---

Step 2: Generate an Embedding

Python

from prompty import invoke

vector = invoke("embed.prompty", inputs={"text": "Prompty is awesome"})

print(type(vector))    # <class 'list'>
print(len(vector))     # 1536 (for text-embedding-3-small)
print(vector[:5])      # [0.0123, -0.0456, 0.0789, ...]

The result is a list[float] — one embedding vector for the input text.

Async works the same way:

from prompty import invoke_async

vector = await invoke_async("embed.prompty", inputs={"text": "Prompty is awesome"})

TypeScript

import { invoke } from "@prompty/core";
import "@prompty/openai"; // registers provider

const vector = await invoke("embed.prompty", { text: "Prompty is awesome" });

console.log(Array.isArray(vector));  // true
console.log(vector.length);          // 1536
console.log(vector.slice(0, 5));     // [0.0123, -0.0456, 0.0789, ...]

C#

using Prompty.Core;

var vector = await Pipeline.InvokeAsync("embed.prompty", new() { ["text"] = "Prompty is awesome" });

// vector is List<float> with 1536 dimensions (for text-embedding-3-small)
Console.WriteLine(vector);

Rust

Caution

The Rust runtime does not yet support apiType: embedding. This feature is planned for a future release.

---

Batch Embeddings

To embed multiple texts at once, pass a list. The API handles batching efficiently in a single request:

batch-embed.prompty

---
name: batch-embedder
description: Embed multiple texts in one call
model:
  id: text-embedding-3-small
  provider: openai
  apiType: embedding
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
inputs:
  - name: texts
    kind: array
    description: List of texts to embed
---
{{texts}}

Python

from prompty import invoke

texts = [
    "What is machine learning?",
    "How do neural networks work?",
    "Explain gradient descent",
]

vectors = invoke("batch-embed.prompty", inputs={"texts": texts})

print(len(vectors))        # 3 (one vector per input text)
print(len(vectors[0]))     # 1536

TypeScript

import { invoke } from "@prompty/core";
import "@prompty/openai"; // registers provider

const texts = [
  "What is machine learning?",
  "How do neural networks work?",
  "Explain gradient descent",
];

const vectors = await invoke("batch-embed.prompty", { texts });

console.log(vectors.length);     // 3
console.log(vectors[0].length);  // 1536

C#

using Prompty.Core;

var texts = new[]
{
    "What is machine learning?",
    "How do neural networks work?",
    "Explain gradient descent",
};

var vectors = await Pipeline.InvokeAsync("batch-embed.prompty", new() { ["texts"] = texts });

// vectors is List<List<float>> — one vector per input text
Console.WriteLine(vectors);

Rust

Caution

The Rust runtime does not yet support apiType: embedding. This feature is planned for a future release.

---

Microsoft Foundry Embeddings

Switch to Microsoft Foundry by changing the provider and connection:

embed-foundry.prompty

---
name: foundry-embedder
model:
  id: ${env:AZURE_OPENAI_EMBEDDING_DEPLOYMENT}
  provider: foundry
  apiType: embedding
  connection:
    kind: key
    endpoint: ${env:AZURE_AI_PROJECT_ENDPOINT}
    apiKey: ${env:AZURE_AI_PROJECT_KEY}
inputs:
  - name: text
    kind: string
---
{{text}}

The code is identical— only the .prompty file changes:

vector = invoke("embed-foundry.prompty", inputs={"text": "Hello from Foundry"})

---

Use Cases

Semantic Search

Generate embeddings for your document corpus, store them in a vector database, then embed the user’s query and find nearest neighbors:

from prompty import invoke
import numpy as np

# Embed documents (do this once, store the vectors)
docs = ["Python is a programming language", "Cats are cute animals", "The weather is sunny"]
doc_vectors = [invoke("embed.prompty", inputs={"text": d}) for d in docs]

# Embed a query
query_vector = invoke("embed.prompty", inputs={"text": "coding languages"})

# Cosine similarity
def cosine_sim(a, b):
    a, b = np.array(a), np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

similarities = [cosine_sim(query_vector, dv) for dv in doc_vectors]
best_match = docs[np.argmax(similarities)]
print(best_match)  # "Python is a programming language"

RAG (Retrieval Augmented Generation)

Combine embeddings with a chat prompt — retrieve relevant context, then pass it to a chat completion:

from prompty import invoke

# 1. Embed the user's question
query = "How do I install Prompty?"
query_vector = invoke("embed.prompty", inputs={"text": query})

# 2. Search your vector store for relevant docs
relevant_docs = vector_store.search(query_vector, top_k=3)

# 3. Pass retrieved context to a chat prompt
context = "\n".join(doc.text for doc in relevant_docs)
answer = invoke("rag-chat.prompty", inputs={"question": query, "context": context})

Tip

For production RAG pipelines, consider using batch embeddings to process your document corpus more efficiently — one API call for many texts is much faster than one call per document.

---

Available Embedding Models

Model	Dimensions	Provider
text-embedding-3-small	1536	OpenAI
text-embedding-3-large	3072	OpenAI
text-embedding-ada-002	1536	OpenAI / Microsoft Foundry

Set the model in model.id in your .prompty file. For Azure, use your deployment name as the model.id.

---

Complete Tested Example

A full, tested example you can copy and run:

Python

embeddings.py

"""Generate embeddings with OpenAI.

This example loads an embedding .prompty file and generates a vector.
Used in: how-to/embeddings.mdx
"""
from __future__ import annotations

from prompty import invoke, load

agent = load("embedding.prompty")
vector = invoke(agent, inputs={"text": "Prompty is a prompt asset format"})
print(f"Embedding dimensions: {len(vector)}")
print(f"First 5 values: {vector[:5]}")

TypeScript

embeddings.ts

/**
 * Generate text embeddings using an embedding model.
 *
 * @example
 * ```bash
 * OPENAI_API_KEY=sk-... npx tsx examples/embeddings.ts
 * ```
 */
import "@prompty/openai";
import { invoke } from "@prompty/core";
import { resolve } from "node:path";

const promptyFile = resolve(import.meta.dirname, "../../prompts/embedding.prompty");

export async function generateEmbedding(text?: string): Promise<number[]> {
  const result = await invoke(promptyFile, {
    text: text ?? "Prompty is a prompt asset format",
  });
  return result as number[];
}

// Run directly
const embedding = await generateEmbedding();
console.log(`Embedding dimensions: ${embedding.length}`);
console.log(`First 5 values: [${embedding.slice(0, 5).join(", ")}]`);

C#

Embeddings.cs

// Copyright (c) Microsoft. All rights reserved.

using Prompty.Core;
using Prompty.OpenAI;

namespace DocsExamples.Examples;

/// <summary>
/// Generate text embeddings using an embedding .prompty file.
/// </summary>
public static class Embeddings
{
    /// <summary>
    /// Load an embedding .prompty and invoke to get vector embeddings.
    /// The prompty file sets apiType: embedding.
    /// </summary>
    public static async Task<object> RunAsync(
        string promptyPath,
        Dictionary<string, object?>? inputs = null)
    {
        // One-time setup
        new PromptyBuilder()
            .AddOpenAI();

        // Full pipeline — executor dispatches on apiType: embedding
        var result = await Pipeline.InvokeAsync(promptyPath, inputs);
        return result;
    }
}

Rust

Caution

The Rust runtime does not yet support apiType: embedding. This feature is planned for a future release.

Further Reading

• File format reference — full .prompty frontmatter syntax
• Connections — configuring OpenAI and Azure connections
• Production Tutorial — taking prompts to production, including RAG patterns