Summary: Flowise is an open-source, drag-and-drop builder for LLM apps, and its Document Stores feature is the cleanest way to turn a PDF into a chatbot that answers from your own text. You load the file, chunk it, embed it into a vector store, test retrieval inside the store, and only then wire it into a chatflow you can call by API or embed on a site. This walkthrough follows the official Document Stores guide step by step and adds the settings and security defaults that trip people up.
Everything below was checked against the Flowise documentation, the flowiseai.com pricing section and the FlowiseAI GitHub repository on the day this was written. I did not run a paid Flowise Cloud plan for this post, so anything about Cloud is taken from the official pricing text, not from my own account.
What you are building
The goal is a small retrieval-augmented generation (RAG) bot: a user asks "Is kitchen flooring covered?" and the bot answers from a specific policy PDF instead of from the model's general knowledge. The official guide uses a sample home insurance policy called "LibertyGuard Deluxe Homeowners Policy", and the official screenshots at the end of this post come from that same guide, so you can match each step to what you see on screen.
In Flowise terms you need four building blocks:
- A Document Loader that reads the PDF (the guide uses the PDF Loader; the docs recommend the generic File Loader if you will mix file types).
- A Text Splitter that cuts the text into chunks.
- An Embeddings model and a Vector Store where those chunks are stored as vectors.
- A chatflow or agentflow that retrieves the best chunks and passes them to a chat model.
Step 1: Install Flowise or open Flowise Cloud
The docs are blunt about the trade-off: self-hosting means you handle setup, database backups and updates, and if you just want the web app they recommend Flowise Cloud at cloud.flowiseai.com. For learning, local is fine and costs nothing.
Local install with npm
- Install Node.js. The docs list Node
v18.15.0orv20and above as supported. - Run
npm install -g flowise. - Start it with
npx flowise start. - Open
http://localhost:3000in your browser.
Local install with Docker
Clone the FlowiseAI/Flowise repository, go into the docker folder, copy .env.example to .env, and run docker compose up -d. The app is again on port 3000, and docker compose stop brings it down. Docker is the better choice if you plan to keep the instance running, because your settings live in one .env file.
From version 3.0.1, Flowise uses email and password accounts with JWT tokens stored in HTTP-only cookies. On first launch you create an admin account. If you are upgrading from an older install that used the deprecated username and password variables, the docs say you must first authenticate with those old credentials before you can set up the new admin account.
Step 2: Create a Document Store and pick a loader
- Open Document Stores from the left menu and click Add New.
- Give the store a descriptive name. One store per knowledge base (one product, one policy set, one handbook) keeps things easy to refresh later.
- Open the store and click Add Document Loader. Choose PDF File for a PDF, or File Loader if you expect PDFs, DOCX and TXT side by side.
- Upload the file. Optionally add a metadata key such as
company: "liberty". The guide calls this good practice because that key is copied into every chunk, so you can later filter to just this dataset even if several datasets share one vector index.
Step 3: Choose a text splitter and chunk size
Below the loader you pick a splitter. The guide uses the Recursive Character Text Splitter, which tries to keep paragraphs and sections intact while staying under a size limit. Other options include character, token, Markdown, code and HTML-to-Markdown splitters; pick Markdown or HTML-to-Markdown when your source has headings you want respected.
The two numbers that matter:
- Chunk Size: the maximum size of each piece.
- Chunk Overlap: how much text consecutive pieces share.
The official example uses chunk_size=1500 and a deliberately generous chunk_overlap=750. The reason is tied to retrieval depth: the vector store returns only the top K chunks (4 by default), so if an answer spans a chunk boundary, overlap makes it more likely that the full answer still lands inside those four chunks. The cost is more chunks to embed and more tokens sent to the model. My suggestion is to start with the guide's values for dense legal or policy text, and reduce overlap for loosely structured notes where each paragraph stands alone.
Click Preview Chunks before going further. If you see tables torn in half or headings separated from their paragraphs, change the splitter now; it is far cheaper than re-embedding later.
Step 4: Process, then configure the upsert
When the preview looks right, click Process. You can still edit or delete individual chunks afterwards, which is useful for removing a boilerplate footer that repeats on every page.
Next, click Upsert Config and fill in three cards:
- Select Embeddings. The guide uses OpenAI embeddings. Whatever you choose, note its output dimensions.
- Select Vector Store. The guide uses Upstash; Pinecone, Qdrant and others are available. This is also where you set top K.
- Select Record Manager (optional). It keeps a record of what was upserted, so re-uploading an updated document does not store duplicate vectors. If you will refresh the data regularly, set it up now.
The single most common upsert error is a dimension mismatch. The docs state that the embedding model and the vector store index must have the same number of dimensions, otherwise upsertion fails. If you created an index for one embedding model and later switch models, create a new index rather than reusing the old one.
Click Upsert. In the guide, the policy PDF ended up as 85 chunks in the vector store.
Step 5: Test retrieval before building any chat
This is the step most tutorials skip. Inside the Document Store, click Retrieval Query and type a real user question. You will see exactly which chunks come back, up to your top K. If the right passage is missing here, no prompt in the chatflow will fix it. Adjust chunking, overlap or top K first, then retest.
A quick checklist I use for this test: ask one question whose answer sits in a single paragraph, one whose answer spans two sections, and one the document does not answer at all. The third tells you what the bot will do when it should say "I don't know".
Step 6: Connect the store to a chatflow
Now create a chatflow (or an Agentflow V2 flow; the docs mark Agentflow V1 as deprecating). You have two options shown in the guide: use the Document Store (Vector) node, which points at the store you just built, or connect directly to the vector store and embeddings nodes. The Document Store node is simpler because chunking and embedding settings stay in one place.
Add a chat model, connect the retriever, save, and open the chat panel to ask the same three test questions. If you want to show users where an answer came from, the embed widget accepts "returnSourceDocuments": true inside chatflowConfig.
Step 7: Call it by API, lock it down, embed it
Prediction API
Every flow gets an endpoint: POST /api/v1/prediction/:id with a JSON body whose only required field is question (or form). Optional fields include streaming, overrideConfig and history. Official SDKs exist: pip install flowise for Python and npm install flowise-sdk for TypeScript.
Protect the flow
Here is the default that surprises people: according to the docs, a new chatflow or agentflow is public, and anyone who has its chatflow ID can run predictions through the embed or the API. To restrict it, go to API Keys, use the DefaultKey or create one, then assign that key to the chatflow. Calls then need Authorization: Bearer <your-api-key>.
Keep the data fresh
When the source changes, the Document Store API lets you upsert into an existing loader (/api/v1/document-store/upsert/<storeId>, with docId, and replaceExisting to swap files) or re-process every loader with /api/v1/document-store/refresh/<storeId>. File-based loaders need the request sent as form data, not JSON, and the file type must match the loader.
Embed on a website
Copy the widget script from the flow and paste it inside your page's <body>. It loads flowise-embed and takes your chatflowid and apiHost.
Self-hosted vs Flowise Cloud plans
| Option | Price | Flows and usage | Storage and team |
|---|---|---|---|
| Self-hosted (open source) | $0 for the software; you pay your own server and model API costs | No plan caps; limited by your hardware and model provider | Your own database; code is Apache 2.0 except the enterprise folder, which is under a commercial license |
| Cloud Free | $0/month | 2 flows and assistants, 100 predictions/month | 5MB storage, evaluations and metrics, community support |
| Cloud Starter | $35/month (first month free per the pricing page) | Unlimited flows and assistants, 10,000 predictions/month | 1GB storage, community support |
| Cloud Pro | $65/month | 50,000 predictions/month | 10GB storage, unlimited workspaces, 5 users plus $15/user/month, admin roles, priority support |
For a PDF bot, the Cloud Free plan's 5MB storage and 100 predictions a month are enough to try the workflow on one small document, not to run it for a team. Model and embedding costs from your provider are separate in every option.
Editor's note
Good fit: people who want a visual RAG pipeline they can inspect chunk by chunk, small teams that need an internal Q&A bot on their own server, and developers who want a REST endpoint without writing a retrieval stack.
Not a great fit: anyone who wants a finished end-user chat product with no setup (a hosted assistant is faster), or teams that cannot maintain a server and do not want a paid Cloud plan.
Gotchas and fixes:
- Upsert fails right away: check that the embedding dimensions match the vector index dimensions.
- Duplicate answers after re-uploading a file: add a Record Manager before the next upsert.
- Embedded widget shows a CORS error ("blocked by CORS policy"): set
CORS_ORIGINSandIFRAME_ORIGINS(the docs show*; use your own domain in production), for examplenpx flowise start --CORS_ORIGINS=* --IFRAME_ORIGINS=*, or put them indocker/.env. - Embedded bot never receives messages: streaming changed in v2.1.0; update Flowise, or pin
flowise-embed@1.3.14for older servers. - Security: set your own
JWT_AUTH_TOKEN_SECRET,TOKEN_HASH_SECRETandEXPRESS_SESSION_SECRET; the docs warn that defaults make forged tokens more likely.
FAQ
Where do I find the Document Store ID and loader ID for the API?
In the browser URL when you open the store and the loader. The View API button on a loader also shows which config values you can override.
Can I use a local model instead of OpenAI?
Yes. Flowise lists many chat model and embedding integrations, including local ones; just keep the embedding dimensions consistent with your vector index.
Is Flowise fully open source?
Mostly. The repository's license file says everything outside the enterprise directory (and a few files marked otherwise) is Apache 2.0, while the enterprise code is under a commercial license.
Related reading on this blog: Dify Playbook: Turn Your Help Docs Into a Support Chatbot for a similar bot in Dify, Pinecone vs Qdrant vs Weaviate for Your First RAG App for picking the vector store, and Langfuse Playbook: Find Costly and Bad LLM Answers, which Flowise can send traces to.
Test retrieval inside the Document Store first, and the chatbot part becomes the easy step.
See the official screenshots at the end of this post. Image credit: screenshots from the official Flowise documentation (Document Stores guide, docs.flowiseai.com).
Last verified: 2026-11-10
Sources: Flowise Get Started, Document Stores guide, Prediction API, Flow-level access control, App-level authentication, Embed widget, Flowise pricing (flowiseai.com), Flowise license.
댓글
댓글 쓰기