Ask & Generate

Utilisez orka.ask() pour le Q&A avec RAG et orka.generate() pour la génération LLM directe.

Méthodes d'Import

Import standard :

import { createOrka, OpenAIAdapter, MemoryVectorAdapter } from 'orkajs';

Import tree-shakeable (recommandé pour production) :

import { createOrka } from 'orkajs/core';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import { MemoryVectorAdapter } from 'orkajs/adapters/memory';

orka.ask()

La méthode principale pour le question-réponse. Quand une base de connaissances est spécifiée, Orka AI effectue automatiquement du RAG (Retrieval-Augmented Generation). C'est la méthode la plus puissante pour construire des systèmes de Q&A.

// Basic usage with RAG
const result = await orka.ask({
  question: 'How do I reset my password?',
  knowledge: 'support-docs',  // Name of your knowledge base
});
 
console.log(result.answer);  // "To reset your password, go to Settings > Security..."
 
// Advanced usage with all options
const result = await orka.ask({
  question: 'How do I reset my password?',
  knowledge: 'support-docs',
  systemPrompt: 'You are a helpful support agent. Be concise and friendly.',
  topK: 5,                    // Number of context chunks to retrieve
  minScore: 0.7,              // Minimum similarity score for chunks
  temperature: 0.7,           // LLM creativity (0-1)
  maxTokens: 1024,            // Maximum response length
  includeContext: true,       // Return retrieved chunks in result
});
 
console.log(result.answer);           // The generated answer
console.log(result.context);          // Array of retrieved chunks
console.log(result.latencyMs);        // Total execution time
console.log(result.usage.totalTokens); // Tokens consumed

Paramètres

question: stringrequired

La question à répondre. Peut être n'importe quelle requête en langage naturel.

knowledge?: string

Nom de la base de connaissances à rechercher. Si omis, pas de RAG (appel LLM direct).

topK?: numberdefault: 5

Nombre de chunks de contexte à récupérer de la base de connaissances.

minScore?: number

Score de similarité minimum (0-1) pour les chunks récupérés. Filtre les résultats peu pertinents.

systemPrompt?: string

Prompt système personnalisé pour contrôler le comportement et le ton du LLM.

temperature?: numberdefault: 0.7

Niveau de créativité du LLM (0-1). Plus bas = plus déterministe, plus haut = plus créatif.

includeContext?: booleandefault: false

Si vrai, retourne les chunks récupérés dans result.context pour le débogage ou l'affichage.

Valeur de Retour

interface AskResult {
  answer: string;           // The generated answer
  context?: ChunkResult[];  // Retrieved chunks (if includeContext: true)
  latencyMs: number;        // Total execution time in milliseconds
  usage: {
    promptTokens: number;   // Tokens in the prompt
    completionTokens: number; // Tokens in the response
    totalTokens: number;    // Total tokens consumed
  };
}

orka.generate()

Génération LLM directe sans RAG. Utilisez pour des tâches créatives, transformations de texte, résumé, ou toute tâche qui ne nécessite pas de connaissances externes.

// Simple generation
const response = await orka.generate('Write a haiku about TypeScript');
console.log(response); // "Types flow like water..." (string)
 
// With options
const response = await orka.generate('Summarize this article: [article text]', {
  temperature: 0.3,      // Lower for more deterministic output
  maxTokens: 200,        // Limit response length
  systemPrompt: 'You are a professional summarizer. Be concise.',
});
 
// Creative writing
const story = await orka.generate('Write a short story about a robot', {
  temperature: 0.9,      // Higher for more creativity
  maxTokens: 1000,
  systemPrompt: 'You are a creative fiction writer.',
});
 
// Code generation
const code = await orka.generate('Write a TypeScript function to sort an array', {
  temperature: 0.2,      // Low for precise code
  systemPrompt: 'You are an expert TypeScript developer. Return only code.',
});

Paramètres

prompt: stringrequired

Le prompt à envoyer au LLM. Peut être n'importe quel texte ou instruction.

options.temperature?: numberdefault: 0.7

Contrôle l'aléatoire. 0 = déterministe, 1 = créativité maximale.

options.maxTokens?: number

Nombre maximum de tokens dans la réponse. Limite la longueur de sortie.

options.systemPrompt?: string

Prompt système pour définir le rôle et le comportement du LLM.

orka.embed()

Générez des embeddings vectoriels pour du texte. Les embeddings sont des vecteurs de haute dimension qui capturent le sens sémantique. Utilisez pour des comparaisons de similarité personnalisées, du clustering, ou construire vos propres systèmes de récupération.

// Single text embedding
const [embedding] = await orka.embed('Hello world');
console.log(embedding.length); // e.g., 1536 (depends on model)
console.log(embedding[0]);     // e.g., 0.0234 (first dimension)
 
// Multiple texts (batched for efficiency)
const embeddings = await orka.embed([
  'How do I reset my password?',
  'I forgot my login credentials',
  'What is the weather today?',
]);
 
// Compare similarity (cosine similarity)
function cosineSimilarity(a: number[], b: number[]): number {
  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dot / (magA * magB);
}
 
const sim1 = cosineSimilarity(embeddings[0], embeddings[1]); // ~0.85 (similar)
const sim2 = cosineSimilarity(embeddings[0], embeddings[2]); // ~0.45 (different)

Quand utiliser orka.embed()

Utilisez orka.embed() quand vous avez besoin d'embeddings bruts pour une logique personnalisée. Pour le RAG standard, utilisez orka.knowledge.create() et orka.ask() — ils gèrent les embeddings automatiquement.

Exemple Complet

ask-generate-example.ts

import { createOrka, OpenAIAdapter, MemoryVectorDB } from 'orkajs';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: new MemoryVectorDB(),
});
 
// 1. Create a knowledge base
await orka.knowledge.create({
  name: 'product-docs',
  source: [
    'Our product supports dark mode. Go to Settings > Appearance to enable it.',
    'To reset your password, click "Forgot Password" on the login page.',
    'Premium users get unlimited API calls and priority support.',
  ],
});
 
// 2. Ask questions with RAG
const result = await orka.ask({
  question: 'How do I enable dark mode?',
  knowledge: 'product-docs',
  topK: 3,
  includeContext: true,
});
 
console.log('Answer:', result.answer);
// "To enable dark mode, go to Settings > Appearance."
 
console.log('Sources:', result.context?.map(c => c.content.slice(0, 50)));
// ["Our product supports dark mode. Go to Settings > ..."]
 
// 3. Direct generation (no RAG)
const summary = await orka.generate(
  'Summarize: ' + result.answer,
  { temperature: 0.3, maxTokens: 50 }
);
 
// 4. Get embeddings for custom logic
const [queryEmbed] = await orka.embed('dark mode settings');
console.log('Embedding dimensions:', queryEmbed.length);

Tableau de Comparaison

Méthode	Cas d'Usage	Retourne
`orka.ask()`	Q&A avec RAG optionnel, réponses basées sur les connaissances	`{ answer, context?, usage }`
`orka.generate()`	Écriture créative, transformations, génération de code	`string`
`orka.embed()`	Similarité personnalisée, clustering, récupération manuelle	`number[][]`

Imports Tree-shakeable

// ✅ Import from main package
import { createOrka } from 'orkajs/core';
 
// ✅ Import adapters separately
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import { MemoryVectorDB } from 'orkajs/adapters/memory';