Deploy and Host self hosted RAGFlow Python SDK (Python SDK for Self-Hosted RAG) on Railway

This template deploys a self-hosted RAGFlow stack on Railway.

About Hosting RAGFlow Python SDK open-source software on Railway (self hosted ragflow-sdk for self-hosted RAGFlow on Railway template)

This template runs RAGFlow as five Railway services: the ragflow service (web UI, API, and task executor), Elasticsearch as the document engine, MinIO for file storage, MySQL for metadata, and Redis for the task queue.

Why Deploy RAGFlow Python SDK, the Dify alternative on Railway (Railway Free Trial)

Dify is a capable platform, but its API sits one layer away from the retrieval pipeline you want to tune.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying RAGFlow Python SDK on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for RAGFlow Python SDK self hosting

A Railway deploy and a plain VPS both give you a ragflow endpoint for the SDK.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	All five services from the template, a public domain for `ragflow`, and volumes without a compose file.	A droplet you size yourself, with Docker, `vm.max_map_count`, and the compose stack on you.
AWS	Generated secrets and no VPC or security group setup before your first `retrieve` call.	Fine grained networking and storage control, but EC2, EBS, and firewall rules by hand.
Hetzner	The template deploy with enough memory for Elasticsearch and DeepDoc, billed by usage.	Cheap servers with lots of RAM, but OS updates, backups, and compose upkeep are yours.

Railway trades low level control for a faster working endpoint.

Common Use Cases for hosted RAGFlow Python SDK

Scripting an internal docs knowledge base: One setup script calls create_dataset and sets the embedding model before any upload.
Batch-uploading and parsing a folder: Read each file as bytes, pass them to upload_documents, then call async_parse_documents on the returned IDs. Retry only the failures.
Testing retrieve() thresholds and top_k: Run sample questions through retrieve at a few similarity_threshold and top_k values. You'll see quickly whether chunks are too noisy or the threshold cuts off good matches.
Creating chat assistants and sessions for a support bot: Call create_chat with the dataset ID, open one session per conversation, and stream answers with session.ask. Separate sessions keep one customer's history out of another's answers.
Exposing a RAGFlow chat to existing tools: Point an OpenAI client at the chat's OpenAI-compatible endpoint with your RAGFlow API key. Tools that already speak the OpenAI format can query your documents unchanged.

Dependencies for RAGFlow Python SDK Docker hosted on Railway

Your Python code only talks to one of the five Railway services: the ragflow service, whose domain becomes base_url in RAGFlow(api_key, base_url).

Deployment Dependencies for Managed RAGFlow Python SDK Service (RAG Engine)

The stack is ragflow (volume /ragflow/logs, health check at /api/v1/system/healthz), Elasticsearch 8.11.3 as the document engine (1 GB heap, volume /usr/share/elasticsearch/data), MinIO via pgsty/silo for uploads (volume /data), MySQL 8.4.11 with database rag_flow (volume /var/lib/mysql), and Redis 8.2.10 for the task queue (volume /data).

Implementation Details for RAGFlow Python SDK (Using RAGFlow official docker image)

The ragflow service runs the official image with /ragflow/entrypoint.sh --enable-adminserver --init-model-provider-tables.

How does RAGFlow Python SDK compare against other ways to call a self-hosted RAG engine from Python

ragflow-sdk is a thin client over RAGFlow's HTTP API, so it sits differently from the frameworks and platforms below.

RAGFlow Python SDK vs LlamaIndex (LlamaIndex Alternative)

Where the work lives: ragflow-sdk calls a RAG engine that already handles parsing, chunking, and retrieval on the server. LlamaIndex makes you assemble those pieces yourself.
Setup effort: A dataset, upload, parse, and retrieve cycle takes a few SDK calls.
Where LlamaIndex wins: If you need custom indexes or swappable components, LlamaIndex gives you more control.

RAGFlow Python SDK vs LangChain (LangChain Alternative)

Scope: LangChain covers a broad set of LLM building blocks. ragflow-sdk only talks to RAGFlow.
Retrieval: retrieve returns chunks from a dataset RAGFlow has already parsed and indexed, so you skip writing loaders and splitters.
Where LangChain wins: If your app mixes many model providers, tools, and non-RAG logic, its ecosystem is much wider.

RAGFlow Python SDK vs Dify API (Dify Alternative)

Deployment model: Dify is a full LLM app platform with its own UI and workflows. ragflow-sdk targets a RAGFlow deployment you host yourself on Railway.
Licensing: RAGFlow is Apache-2.0, while Dify uses a modified Apache license with extra conditions, so check those if they matter to you.
Where Dify wins: If you want a visual app builder rather than a RAG engine driven from code, Dify is the stronger fit.

RAGFlow Python SDK vs Haystack (Haystack Alternative)

Abstraction: Haystack, from deepset, builds pipelines from Python components you wire together. ragflow-sdk hands the pipeline to the RAGFlow server and calls it over HTTP.
Parsing: DeepDoc handles PDFs, scans, tables, and slides out of the box.
Where Haystack wins: If you want full control over each component inside one Python process, Haystack gives you that.

How to use RAGFlow Python SDK (the OSS RAG engine)?

Deploy the template, open the ragflow domain, register an account, and add a model provider under Model providers.
Generate an API key from the RAGFlow UI. The menu path isn't in the verified docs, so check the acquire-API-key guide.
Run pip install ragflow-sdk.
Set base_url to your Railway ragflow domain and confirm the API responds, since port 9380 may not be public.
Create a dataset with create_dataset(name="kb_1").
Upload with upload_documents, passing display_name and file bytes as blob.
Parse with async_parse_documents(ids) or parse_documents(ids).
Call retrieve(dataset_ids=[...], question="...").
Call create_chat and create_session, then session.ask(question, stream=True).

from ragflow_sdk import RAGFlow

rag = RAGFlow(api_key="YOUR_API_KEY", base_url="https://your-ragflow.up.railway.app")
dataset = rag.create_dataset(name="kb_1")
with open("handbook.txt", "rb") as f:
    dataset.upload_documents([{"display_name": "handbook.txt", "blob": f.read()}])
chat = rag.create_chat("Support Bot", dataset_ids=[dataset.id])
session = chat.create_session()
for part in session.ask("How do I request leave?", stream=True):
    print(part.content, end="")

How to self host RAGFlow Python SDK on other VPS Services (RAGFlow self hosting guide)

Any VPS with Docker can run the same RAGFlow stack.

Clone the Repository

Clone the upstream repo and move into the docker folder.

git clone https://github.com/infiniflow/ragflow
cd ragflow/docker

Install Dependencies

Your host needs Docker 24 or newer, plus a kernel setting for Elasticsearch.

sudo sysctl -w vm.max_map_count=262144

Persist it in /etc/sysctl.conf so it survives a reboot.

Configure Environment Variables

Copy the example env file and set real values before the first boot, especially the secret key and passwords.

cp .env.example .env
# edit .env: RAGFLOW_SECRET_KEY, ELASTIC_PASSWORD, MYSQL_ROOT_PASSWORD

Keep REGISTER_ENABLED=1 only until your accounts exist.

Start the RAGFlow Python SDK Application

Start the stack detached, then confirm the health endpoint returns 200 before pointing the SDK at it.

docker compose -f docker-compose.yml up -d
curl -i http://your-domain:80/api/v1/system/healthz

Once healthy, create an API key in the UI and connect with RAGFlow(api_key, base_url) using your-domain.

Official Pricing of RAGFlow Python SDK (RAGFlow pricing)

RAGFlow is open source under Apache-2.0, and the ragflow-sdk package is free to install with pip install ragflow-sdk.

RAGFlow Python SDK cloud vs self hosted comparison (Pricing, features, costs, and more)

Self hosting RAGFlow and calling it through ragflow-sdk gives you the same API on Railway or on a VPS you manage.

Monthly cost of self hosting RAGFlow Python SDK on Railway

Railway typically lands around $40-80 per month for this template, mostly for Elasticsearch, MySQL, and the RAGFlow container with DeepDoc models.

System Requirements for Hosting RAGFlow Python SDK on a VPS

Upstream RAGFlow lists minimums of 4 CPU cores, 16 GB RAM, 50 GB disk, and Docker 24 or newer.

Frequently Asked Questions (FAQs)

Do I need to set embedding_model before uploading?

Yes, it can only change while chunk_count is 0.

Why does retrieve return nothing for an empty question?

The question argument must be a non-empty string, and an empty one returns an empty result rather than an error.

How do I check error code versus HTTP status?

Check both.

Can I use the OpenAI client instead of ragflow-sdk?

Yes, for chat.

What does parse_documents return?

It blocks until parsing reaches a terminal state and returns tuples of (document_id, status, chunk_count, token_count).

How do I bulk delete datasets safely?

Pass the ids you mean to delete explicitly, since an empty ids list deletes nothing.