OpenAI

Ragfish provides OpenAI integration through the @ragfish/openai package.

The package provides the OpenAI implementations required to use OpenAI language models and embedding models with the Ragfish Core Framework.

The integration includes:

1. OpenAILLM — OpenAI language model integration

2. OpenAIEmbedding — OpenAI embedding integration

These components can be configured through the Settings object provided by @ragfish/core.

Installation

Install the OpenAI integration package:

npm install @ragfish/openai

Make sure @ragfish/core is also installed:

npm install @ragfish/core

Environment Configuration

Store your OpenAI API key in an environment variable.

OPENAI_API_KEY=your-api-key

Do not hard-code API keys in your application source code or commit them to version control.

Configure OpenAI

Import the OpenAI implementations:
import {
 OpenAILLM,
 OpenAIEmbedding
} from "@ragfish/openai";

Then configure them through Ragfish Settings:

import { Settings } from "@ragfish/core";

Settings.llm = new OpenAILLM({
 apiKey: process.env.OPENAI_API_KEY
});

Settings.embedModel = new OpenAIEmbedding({
 apiKey: process.env.OPENAI_API_KEY
});

Ragfish keeps the provider implementation in @ragfish/openai, while the configuration mechanism is provided by @ragfish/core.

OpenAI LLM

OpenAILLM provides the language model integration used to generate AI responses.

Configure it using Settings.llm:

import { Settings } from "@ragfish/core";
import { OpenAILLM } from "@ragfish/openai";

Settings.llm = new OpenAILLM({
 apiKey: process.env.OPENAI_API_KEY
});

Once configured, Ragfish components such as Chat can use the configured language model.

page.

For model-specific configuration, refer to the OpenAI LLM Page.

OpenAI Embeddings

OpenAIEmbedding provides the embedding integration used by the RAG retrieval pipeline.

Configure it using Settings.embedModel:

import { Settings } from "@ragfish/core";
import { OpenAIEmbedding } from "@ragfish/openai";

Settings.embedModel = new OpenAIEmbedding({
 apiKey: process.env.OPENAI_API_KEY
});

page.

Embeddings are used to represent knowledge and queries as vectors for semantic retrieval.

For embedding-specific configuration, refer to the OpenAI Embeddings page.

OpenAI in the Ragfish Pipeline

OpenAI can participate in two stages of a Ragfish application:

      OpenAI
                     │
            ┌────────┴────────┐
            │                 │
            ▼                 ▼
       OpenAILLM      OpenAIEmbedding
            │                 │
            ▼                 ▼
      Generate            Generate
      Response             Vectors
                              │
                              ▼
                        Vector Store
                              │
                              ▼
                          Retrieval

The language model generates the final response, while the embedding model supports semantic retrieval.

OpenAI with Qdrant

OpenAI can be combined with the Ragfish Qdrant integration to create a complete RAG application.

OpenAIEmbedding
      │
      ▼
QdrantVectorStore
      │
      ▼
QdrantRetriever
      │
      ▼
Chat
      │
      ▼
OpenAILLM
      │
      ▼
Response

A complete configuration looks like:

import { Settings, Chat } from "@ragfish/core";

import {
 OpenAILLM,
 OpenAIEmbedding
} from "@ragfish/openai";

import {
 QdrantVectorStore,
 QdrantRetriever
} from "@ragfish/qdrant";

Settings.embedModel = new OpenAIEmbedding({
 apiKey: process.env.OPENAI_API_KEY
});

Settings.llm = new OpenAILLM({
 apiKey: process.env.OPENAI_API_KEY
});

const store = new QdrantVectorStore({
 // Qdrant configuration
});

const retriever = new QdrantRetriever({
 vectorStore: store,
 collectionName: "knowledge"
});

const chat = new Chat({
 retriever
});

This follows the architecture defined in the Ragfish framework example, where OpenAI models are combined with Qdrant retrieval and the Core Chat component.

Ask a Question

Once the models and retriever are configured, you can send a question through Chat:

const response = await chat.message(
 "What is Ragfish?"
);

console.log(response);

The request follows the RAG pipeline:

User Question
     │
     ▼
OpenAI Embedding
     │
     ▼
Vector Search
     │
     ▼
Relevant Knowledge
     │
     ▼
OpenAI LLM
     │
     ▼
AI Response

Complete Example

import { Settings, Chat } from "@ragfish/core";

import {
 OpenAILLM,
 OpenAIEmbedding
} from "@ragfish/openai";

import {
 QdrantVectorStore,
 QdrantRetriever
} from "@ragfish/qdrant";

Settings.embedModel = new OpenAIEmbedding({
 apiKey: process.env.OPENAI_API_KEY
});

Settings.llm = new OpenAILLM({
 apiKey: process.env.OPENAI_API_KEY
});

const store = new QdrantVectorStore({
 // Qdrant configuration
});

const retriever = new QdrantRetriever({
 vectorStore: store,
 collectionName: "knowledge"
});

const chat = new Chat({
 retriever
});

const response = await chat.message(
 "What is Ragfish?"
);

console.log(response);

Provider Independence

The OpenAI integration is intentionally separated from the Ragfish Core Framework.

@ragfish/core
     │
     │ Core interfaces
     ▼
@ragfish/openai
     │
     ├── OpenAILLM
     └── OpenAIEmbedding

This architecture allows Ragfish to add additional AI providers without changing the core application architecture.

Best Practices

When using OpenAI with Ragfish:

1. Store API credentials in environment variables.

2. Configure the provider during application startup.

3. Keep provider configuration separate from application logic.

4. Configure both the LLM and embedding model when building a RAG application.

5. Use the Ragfish provider package instead of directly coupling application components to provider-specific APIs.

6. Keep provider-specific configuration isolated so that the provider can be changed later if required.

After completing the OpenAI integration, you can explore the other AI providers as they become available.