Templates de Prompts

Construisez des prompts réutilisables et composables avec des variables, des exemples few-shot, des rôles de chat et du pré-remplissage partiel. Structurez vos interactions LLM pour des sorties cohérentes et de haute qualité.

Pourquoi des Templates de Prompts ?

Les prompts codés en dur sont fragiles et difficiles à maintenir. Les templates de prompts séparent la structure des données, permettant la réutilisation, les tests et l'itération. Ils appliquent également la validation des variables, empêchant les erreurs d'exécution dues aux entrées manquantes.

❌ Sans Templates

// Hard-coded, no validation, hard to reuse
const prompt = `You are a ${role}.
Translate "${text}" to ${language}.`;
 
// Missing variable? Silent bug!
// Changing format? Edit every prompt!

✅ Avec Templates

const tmpl = PromptTemplate.fromTemplate(
  'You are a {{role}}.\nTranslate "{{text}}" to {{language}}.'
);
 
// Validates all variables
const prompt = tmpl.format({
  role: 'translator',
  text: 'Hello',
  language: 'French'
});

# PromptTemplate — Templates de Base

La base de l'ingénierie de prompts dans Orka AI. Définissez un template avec des {{variables}}, puis formatez-le avec des valeurs concrètes. Les variables sont validées au moment du formatage — les variables manquantes lèvent des erreurs claires.

import { PromptTemplate } from 'orkajs/templates/prompt';
 
// Method 1: fromTemplate (auto-detects variables)
const template = PromptTemplate.fromTemplate(
  'Summarize the following {{format}} document about {{topic}}:\n\n{{content}}'
);
 
console.log(template.getInputVariables());
// ['format', 'topic', 'content']
 
const prompt = template.format({
  format: 'technical',
  topic: 'machine learning',
  content: 'Deep learning is a subset of machine learning...'
});
 
// Result:
// "Summarize the following technical document about machine learning:
//
// Deep learning is a subset of machine learning..."
 
// Method 2: Constructor (explicit variables)
const template2 = new PromptTemplate({
  template: 'Translate "{{text}}" from {{source}} to {{target}}.',
  inputVariables: ['text', 'source', 'target'],
  validateTemplate: true  // Throws if variables don't match
});

# Prompts Partiels — Variables Pré-remplies

Les prompts partiels vous permettent de pré-remplir certaines variables, créant un nouveau template qui ne nécessite que les variables restantes. C'est puissant pour créer des versions spécialisées de templates génériques.

import { PromptTemplate } from 'orkajs/templates/prompt';
 
// Generic translation template
const translationTemplate = PromptTemplate.fromTemplate(
  'You are a professional {{language}} translator.\nTranslate the following text to {{language}}:\n\n{{text}}'
);
 
// Create a French-specific template (partially applied)
const frenchTranslator = translationTemplate.partial({
  language: 'French'
});
 
console.log(frenchTranslator.getInputVariables());
// ['text']  — only 'text' remains!
 
const prompt = frenchTranslator.format({
  text: 'Hello, how are you?'
});
// "You are a professional French translator.
// Translate the following text to French:
//
// Hello, how are you?"
 
// Dynamic partial variables (functions)
const timestampTemplate = PromptTemplate.fromTemplate(
  '[{{timestamp}}] {{role}}: {{message}}'
);
 
const withTimestamp = timestampTemplate.partial({
  timestamp: () => new Date().toISOString()  // Evaluated at format time
});
 
const prompt2 = withTimestamp.format({
  role: 'System',
  message: 'Server started'
});
// "[2024-01-15T10:30:00.000Z] System: Server started"

💡 Variables Partielles : String vs Fonction

String — Valeur statique, définie une fois: { language: 'French' }
Function — Valeur dynamique, évaluée à chaque appel de format(): { timestamp: () => Date.now().toString() }

# ChatPromptTemplate — Messages Chat avec Rôles

Les LLMs modernes utilisent des APIs basées sur le chat avec des rôles system, user et assistant. ChatPromptTemplate structure vos prompts comme une séquence de messages basés sur les rôles, chacun avec son propre template et ses variables.

import { ChatPromptTemplate } from 'orkajs/templates/chat';
 
// Create from message tuples [role, template]
const chatTemplate = ChatPromptTemplate.fromMessages([
  ['system', 'You are a {{role}} expert. Always respond in {{language}}.'],
  ['user', '{{question}}']
]);
 
console.log(chatTemplate.getInputVariables());
// ['role', 'language', 'question']
 
// Format returns ChatMessage[] — ready for LLM
const messages = chatTemplate.format({
  role: 'TypeScript',
  language: 'French',
  question: 'What are generics?'
});
 
console.log(messages);
// [
//   { role: 'system', content: 'You are a TypeScript expert. Always respond in French.' },
//   { role: 'user', content: 'What are generics?' }
// ]
 
// Use directly with LLM
const result = await orka.getLLM().generate('', { messages });

Conversations Multi-tours

Construisez des templates de conversation avec des réponses assistant pour des interactions contextuelles.

const conversationTemplate = ChatPromptTemplate.fromMessages([
  ['system', 'You are a helpful coding assistant specializing in {{language}}.'],
  ['user', 'How do I create a {{dataStructure}} in {{language}}?'],
  ['assistant', 'Here is how to create a {{dataStructure}} in {{language}}:'],
  ['user', 'Now show me how to {{operation}} with it.']
]);
 
const messages = conversationTemplate.format({
  language: 'TypeScript',
  dataStructure: 'linked list',
  operation: 'reverse'
});
 
// Creates a 4-message conversation with proper roles

# Templates Chat Partiels

// Create a base template
const baseChat = ChatPromptTemplate.fromMessages([
  ['system', 'You are a {{role}} assistant. Respond in {{format}} format.'],
  ['user', '{{question}}']
]);
 
// Specialize for JSON responses
const jsonChat = baseChat.partial({
  format: 'JSON'
});
 
// Now only needs 'role' and 'question'
const messages = jsonChat.format({
  role: 'data analysis',
  question: 'List the top 5 programming languages'
});

# FewShotPromptTemplate — Apprentissage par l'Exemple

Le few-shot prompting est l'une des techniques les plus efficaces pour guider le comportement du LLM. En fournissant des exemples de paires entrée-sortie, vous enseignez au modèle le format et le style exacts que vous attendez. FewShotPromptTemplate rend cela structuré et réutilisable.

import { FewShotPromptTemplate } from 'orkajs/templates/few-shot';
 
const fewShotTemplate = new FewShotPromptTemplate({
  // Examples that teach the model
  examples: [
    { input: 'happy', output: 'sad' },
    { input: 'tall', output: 'short' },
    { input: 'fast', output: 'slow' },
  ],
 
  // How each example is formatted
  examplePrompt: 'Input: {{input}}\nOutput: {{output}}',
 
  // Text before examples
  prefix: 'Give the antonym of every input word.',
 
  // Text after examples (with the actual question)
  suffix: 'Input: {{input}}\nOutput:',
 
  // Variables the user must provide
  inputVariables: ['input'],
 
  // Separator between examples
  exampleSeparator: '\n\n'
});
 
const prompt = fewShotTemplate.format({ input: 'bright' });

Cela génère :

Give the antonym of every input word.
 
Input: happy
Output: sad
 
Input: tall
Output: short
 
Input: fast
Output: slow
 
Input: bright
Output:

# Exemples Dynamiques

Ajoutez des exemples dynamiquement en fonction du contexte ou du comportement utilisateur.

const template = new FewShotPromptTemplate({
  examples: [],  // Start empty
  examplePrompt: 'Question: {{question}}\nSQL: {{sql}}',
  prefix: 'Convert natural language to SQL queries.',
  suffix: 'Question: {{question}}\nSQL:',
  inputVariables: ['question']
});
 
// Add examples based on the database schema
template.addExamples([
  {
    question: 'How many users are there?',
    sql: 'SELECT COUNT(*) FROM users;'
  },
  {
    question: 'Find all active orders',
    sql: "SELECT * FROM orders WHERE status = 'active';"
  },
  {
    question: 'Get the top 10 products by revenue',
    sql: 'SELECT name, SUM(price * quantity) as revenue FROM products GROUP BY name ORDER BY revenue DESC LIMIT 10;'
  }
]);
 
const prompt = template.format({
  question: 'What are the most popular categories?'
});

# Exemples Few-Shot Concrets

🏷️ Classification

const classifier = new FewShotPromptTemplate({
  examples: [
    { text: 'I love this product!', label: 'positive' },
    { text: 'Terrible experience', label: 'negative' },
    { text: 'It works fine', label: 'neutral' },
  ],
  examplePrompt: 'Text: "{{text}}"\nSentiment: {{label}}',
  prefix: 'Classify the sentiment of each text.',
  suffix: 'Text: "{{text}}"\nSentiment:',
  inputVariables: ['text']
});

📝 Extraction de Données

const extractor = new FewShotPromptTemplate({
  examples: [
    {
      text: 'John Smith, CEO of Acme Corp, announced...',
      output: '{"name": "John Smith", "title": "CEO", "company": "Acme Corp"}'
    },
    {
      text: 'Dr. Jane Doe from MIT published...',
      output: '{"name": "Jane Doe", "title": "Dr.", "company": "MIT"}'
    }
  ],
  examplePrompt: 'Text: {{text}}\nJSON: {{output}}',
  prefix: 'Extract person information as JSON.',
  suffix: 'Text: {{text}}\nJSON:',
  inputVariables: ['text']
});

# Exemple Complet — Tout Combiner

templates-example.ts

import { createOrka, OpenAIAdapter } from 'orkajs/core';
import { ChatPromptTemplate } from 'orkajs/templates/chat';
import { FewShotPromptTemplate } from 'orkajs/templates/few-shot';
import { StructuredOutputParser } from 'orkajs/parsers/structured';
import { CachedLLM } from 'orkajs/cache/llm';
import { MemoryCache } from 'orkajs/cache/memory';
import { z } from 'zod';
 
// Setup
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
const cachedLLM = new CachedLLM(llm, new MemoryCache());
 
const orka = createOrka({ llm: cachedLLM });
 
// 1. Define output schema
const schema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  confidence: z.number().min(0).max(1),
  keywords: z.array(z.string())
});
const parser = StructuredOutputParser.fromZodSchema(schema);
 
// 2. Create few-shot examples
const fewShot = new FewShotPromptTemplate({
  examples: [
    {
      review: 'Amazing product, exceeded expectations!',
      output: '{"sentiment": "positive", "confidence": 0.95, "keywords": ["amazing", "exceeded"]}'
    },
    {
      review: 'Broke after 2 days, waste of money',
      output: '{"sentiment": "negative", "confidence": 0.9, "keywords": ["broke", "waste"]}'
    }
  ],
  examplePrompt: 'Review: "{{review}}"\nAnalysis: {{output}}',
  prefix: 'Analyze product reviews. Return JSON with sentiment, confidence, and keywords.',
  suffix: 'Review: "{{review}}"\nAnalysis:',
  inputVariables: ['review']
});
 
// 3. Create chat template
const chatTemplate = ChatPromptTemplate.fromMessages([
  ['system', 'You are a sentiment analysis expert. {{formatInstructions}}'],
  ['user', '{{fewShotPrompt}}']
]);
 
// 4. Format and call
const fewShotPrompt = fewShot.format({
  review: 'Good quality but shipping was slow'
});
 
const messages = chatTemplate.format({
  formatInstructions: parser.getFormatInstructions(),
  fewShotPrompt: fewShotPrompt
});
 
const result = await orka.getLLM().generate('', { messages });
const analysis = parser.parse(result.content);
 
console.log(analysis);
// { sentiment: 'neutral', confidence: 0.7, keywords: ['good quality', 'slow'] }

Comparaison

Template	Cas d'Usage	Sortie
PromptTemplate	Prompts texte simples avec variables	`string`
ChatPromptTemplate	Messages chat basés sur les rôles	`ChatMessage[]`
FewShotPromptTemplate	Apprentissage par l'exemple	`string`

vs Versioning de Prompts

Orka AI a deux systèmes de prompts complémentaires. Ils fonctionnent ensemble :

Templates de Prompts (cette page)

Composition au build : variables, few-shot, rôles chat, application partielle. Pour structurer comment les prompts sont construits.

Versioning de Prompts (PromptRegistry)

Gestion au runtime : versioning, rollback, diff, persistance. Pour gérer l'évolution des prompts dans le temps.

Bonnes Pratiques

1. Utilisez Few-Shot pour le Contrôle de Format

Quand vous avez besoin d'un format de sortie spécifique (JSON, CSV, texte structuré), les exemples few-shot sont plus fiables que les instructions seules.

2. Utilisez les Partiels pour la Spécialisation

Créez un template générique, puis utilisez .partial() pour créer des versions spécialisées. Cela évite la duplication et assure la cohérence.

3. Utilisez Toujours les Messages System

ChatPromptTemplate facilite l'inclusion de messages system. Définissez toujours le rôle, le ton et les contraintes dans le message system.

4. 3-5 Exemples est Optimal

Pour le few-shot prompting, 3-5 exemples diversifiés donnent généralement les meilleurs résultats. Trop peu et le modèle peut ne pas apprendre le pattern ; trop et cela gaspille des tokens.

Imports Tree-shakeable

// ✅ Import only what you need
import { PromptTemplate } from 'orkajs/templates/prompt';
import { ChatPromptTemplate } from 'orkajs/templates/chat';
import { FewShotPromptTemplate } from 'orkajs/templates/few-shot';
 
// ✅ Or import from index
import { PromptTemplate, ChatPromptTemplate, FewShotPromptTemplate } from 'orkajs/templates';