Internal Knowledge Base – DeepFellow Showcase

A showcase project demonstrating how to build a retrieval-augmented internal knowledge base on top of a self-hosted DeepFellow server, using the AI SDK and Next.js.

DeepFellow exposes an OpenAI-compatible API, so this app talks to it with the standard @ai-sdk/openai provider and the official openai SDK – only the base URL and model IDs differ.

What it demonstrates

• Chat with DeepFellow chat models via the AI SDK (streamText).
• Managed retrieval using DeepFellow's Files + Vector Stores API: uploaded PDFs are sent to /v1/files and attached to a per-user vector store. DeepFellow handles chunking, embedding, and similarity search server-side – there are no embeddings stored in the app's own database.
• RAG via Language Model Middleware – ai/rag-middleware.ts intercepts each chat request, classifies the message, generates a hypothetical answer (HyDE), runs a vector-store search scoped to the user's selected files, and injects the retrieved chunks into the prompt.

Architecture

Concern	Implementation
Chat + embeddings provider	DeepFellow (OpenAI-compatible), configured in ai/client.ts
File storage	DeepFellow /v1/files
Chunking / embedding / search	DeepFellow /v1/vector_stores (server-side)
Retrieval	vectorStores.search inside ai/rag-middleware.ts
App database (Postgres)	users, chats, and pointers to files / vector stores – not embeddings

Note: the DeepFellow server is served entirely under the /v1 prefix (/v1/chat/completions, /v1/files, /v1/vector_stores). Both clients in ai/client.ts set baseURL to https://<host>/v1.

How to use

To run the example locally you need to:

1. Start a Postgres instance using Docker:

   docker run --name postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres

2. Set up a DeepFellow instance by following the installation guide, then create an organization/project and generate an API key. Point the app at your instance by updating BASE_URL in ai/client.ts if it isn't the default host.

3. Configure environment variables – copy ./.env.example to ./.env.local and fill in:

   • OPENAI_API_KEY – your DeepFellow project API key (e.g. dfproj_...).
   • AUTH_SECRET – a random secret (openssl rand -base64 32).
   • POSTGRES_URL – defaults to the connection string for the Docker command above.

4. Install dependencies:

   npm install

5. Run the database migrations:

   npx tsx migrate.ts

6. Start the development server:

   npm run dev

Then register a user, open Manage Knowledge Base, upload a PDF, select it, and ask questions about its contents.

Models

Model IDs are defined in ai/client.ts and must match what your DeepFellow instance serves (check GET /v1/models):

export const SMALL_MODEL = "gpt-5.4-nano";   // classification + HyDE
export const DEFAULT_MODEL = "gpt-5.4-mini"; // chat

Learn More

• DeepFellow Documentation
• AI SDK Documentation
• Next.js Documentation