DeepSeek LlamaIndex Integration: Python RAG Setup

Last verified: April 27, 2026.

DeepSeek LlamaIndex Integration is useful when you want DeepSeek to generate answers from retrieved documents, indexed knowledge bases, or structured context assembled by LlamaIndex. In this setup, LlamaIndex handles the data workflow, and DeepSeek provides the language-model response layer.

LlamaIndex can help with document loading, parsing, chunking, indexing, retrieval, query engines, chat engines, and RAG orchestration. DeepSeek is the LLM/API provider that reads the retrieved context and produces the answer.

This is not the same as using the official DeepSeek web/app, calling the DeepSeek API directly without a retrieval framework, building a LangChain workflow, or using Chat-Deep.ai browser chat. Each path has a different purpose.

Independent site notice: Chat-Deep.ai is an independent DeepSeek guide and browser-access site. It is not affiliated with DeepSeek, DeepSeek.com, the official DeepSeek app, the official DeepSeek developer platform, LlamaIndex, OpenAI, Anthropic, Ollama, LM Studio, vLLM, SGLang, Hugging Face, ModelScope, or any model/runtime provider.

Quick Answer

For most Python RAG projects, install llama-index, install llama-index-llms-deepseek, set DEEPSEEK_API_KEY, import DeepSeek, and use deepseek-v4-flash or deepseek-v4-pro as the model. Configure a separate embedding model for indexing and retrieval.

• Use deepseek-v4-flash for most RAG answers, summaries, extraction, support bots, document Q&A, and high-volume query engines.
• Use deepseek-v4-pro for harder reasoning, long-context synthesis, complex coding, agentic workflows, and high-value production analysis.
• Do not use deepseek-chat or deepseek-reasoner as primary model IDs in new examples.
• Keep API keys server-side and never expose DEEPSEEK_API_KEY in browser code, public repositories, screenshots, logs, frontend bundles, shared notebooks, or static pages.

What DeepSeek + LlamaIndex Actually Means

DeepSeek and LlamaIndex do different jobs. DeepSeek is the language model/API provider. LlamaIndex is the data framework that helps you connect documents, indexes, retrieval, and prompts to a language model.

A complete RAG workflow usually needs:

• Documents or knowledge sources.
• Parsing and chunking.
• An embedding model.
• Vector or index storage.
• A retriever.
• An LLM such as DeepSeek.
• A prompt template or response synthesis strategy.
• Source attribution or citation handling.
• Evaluation, monitoring, and feedback loops.

DeepSeek does not automatically provide the vector database, embedding model, document loader, memory system, or data-ingestion pipeline. LlamaIndex helps organize those pieces, but you still need to choose and configure them carefully.

DeepSeek + LlamaIndex vs Direct DeepSeek API vs LangChain

Path	Best for	What it manages	What to watch
DeepSeek + LlamaIndex	RAG, document Q&A, query engines, chat engines, indexed knowledge bases, and source-aware answers.	Document loading, parsing, indexing, retrieval, context assembly, and response synthesis.	Embedding quality, chunking, retrieval relevance, source attribution, wrapper support, and provider-specific parameters.
Direct DeepSeek API	Simple model calls, direct Chat Completions, structured output, tool calls, and custom app logic without a retrieval framework.	Only the model/API request and response layer.	You must build your own retrieval, indexing, memory, document processing, and evaluation pipeline if needed.
DeepSeek + LangChain	Broad chain orchestration, agent workflows, tool routing, and multi-step app logic.	Chains, agents, tools, prompts, memory patterns, and integrations depending on your setup.	Tool safety, schema validation, provider-specific fields, and whether your main problem is data grounding or orchestration.
Chat-Deep.ai browser chat	Trying prompts, reading guides, and using browser-access chat without building an app.	Independent browser access and editorial guidance.	It is not the official DeepSeek platform and cannot manage official DeepSeek API keys, billing, accounts, or app login.

If your main problem is grounding answers in indexed data, LlamaIndex is usually the better fit. If you only need one direct model call, the DeepSeek API guide may be enough. If your workflow is mostly chain and tool orchestration, compare with the DeepSeek LangChain Integration guide.

Current DeepSeek Model Names for LlamaIndex

DeepSeek-V4 Preview is the current official DeepSeek generation. For new hosted API examples, use these model IDs:

• deepseek-v4-flash
• deepseek-v4-pro

Both current V4 API models are documented with 1M context length, 384K maximum output, thinking and non-thinking modes, JSON Output, Tool Calls, Chat Prefix Completion beta, and FIM Completion beta in non-thinking mode only. For model background, see the DeepSeek Models hub and the DeepSeek V4 guide.

Model	Best LlamaIndex use cases	Starting mode	Notes
deepseek-v4-flash	RAG answers, document Q&A, summaries, extraction, classification, support bots, high-volume query engines, and routine coding help.	Start with non-thinking mode for simple retrieval and extraction tasks.	Use first for most workflows unless quality testing shows the task needs more reasoning.
deepseek-v4-pro	Hard reasoning, complex synthesis, long-context analysis, multi-step troubleshooting, coding-agent workflows, and high-value production answers.	Use thinking mode when reasoning quality matters.	Use for tasks where better synthesis and reasoning justify the slower or heavier route.

The names deepseek-chat and deepseek-reasoner are legacy compatibility aliases. deepseek-chat currently maps to deepseek-v4-flash non-thinking mode, while deepseek-reasoner currently maps to deepseek-v4-flash thinking mode. These aliases are scheduled to be retired after July 24, 2026, 15:59 UTC.

LlamaIndex official examples may still show older names such as deepseek-chat and deepseek-reasoner. Treat those as wrapper-usage examples or migration examples, not as current DeepSeek model-name guidance for new content.

Install LlamaIndex and the DeepSeek Integration

Install the core LlamaIndex package and the DeepSeek LLM integration in a Python virtual environment:

pip install -U llama-index llama-index-llms-deepseek

For the RAG example below, this guide uses a separate embedding model. One common local embedding route is the Hugging Face embedding integration:

pip install -U llama-index-embeddings-huggingface

You can choose a different embedding provider or local embedding model. The important rule is that the embedding model is separate from DeepSeek unless official DeepSeek documentation confirms embedding support for the specific use case you are building.

For production, pin package versions, test upgrades in staging, and keep notebooks private if they include API keys, private files, customer data, or internal documents.

Set Your DeepSeek API Key

Use an environment variable named DEEPSEEK_API_KEY. Do not hard-code keys in code samples, notebooks, Git repositories, Docker images, static pages, or frontend bundles.

Linux or macOS

export DEEPSEEK_API_KEY="replace-with-your-deepseek-api-key"

Windows PowerShell

$env:DEEPSEEK_API_KEY="replace-with-your-deepseek-api-key"

Python environment access

import os

api_key = os.environ["DEEPSEEK_API_KEY"]

The official OpenAI-format DeepSeek base URL is https://api.deepseek.com. DeepSeek also documents an Anthropic-format base URL at https://api.deepseek.com/anthropic, but this article focuses on Python LlamaIndex usage.

Basic Python Setup: DeepSeek as a LlamaIndex LLM

The LlamaIndex Python integration exposes a DeepSeek class. Use the current V4 model IDs in new examples.

import os
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

response = llm.complete(
    "Explain retrieval augmented generation in two short paragraphs."
)

print(response)

Line-by-line notes

• from llama_index.llms.deepseek import DeepSeek imports the LlamaIndex DeepSeek LLM wrapper.
• DEEPSEEK_API_KEY is read from the server-side environment.
• model="deepseek-v4-flash" uses the current hosted DeepSeek V4 Flash API model ID.
• llm.complete(...) sends a simple completion-style request through the wrapper.

If your installed LlamaIndex DeepSeek wrapper rejects deepseek-v4-flash or deepseek-v4-pro, upgrade your LlamaIndex packages, check the installed wrapper version, and review the official LlamaIndex DeepSeek API reference. If wrapper support has not caught up, use LlamaIndex for retrieval and call the DeepSeek API directly for the final generation step until your package version supports the current V4 names reliably.

When to Use deepseek-v4-pro

Use deepseek-v4-pro when the task needs stronger reasoning, careful synthesis, long-context review, multi-step troubleshooting, or complex coding support.

import os
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-pro",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

prompt = """
You are reviewing an internal technical design.

Summarize the architecture, identify the top three risks,
and recommend a safer migration plan.
"""

response = llm.complete(prompt)

print(response)

Do not choose a model name only because it looks newer or larger. Test with your own documents, prompts, retrieval settings, answer-quality requirements, and latency targets.

Chat Messages and Streaming in LlamaIndex

LlamaIndex supports chat-style messages and streaming patterns through its LLM abstractions. Exact provider-specific fields can vary by package version, so test your installed wrapper before relying on DeepSeek-specific behavior such as reasoning_content.

Chat messages

import os
from llama_index.core.llms import ChatMessage
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

messages = [
    ChatMessage(
        role="system",
        content="You are a concise assistant for document Q&A."
    ),
    ChatMessage(
        role="user",
        content="What should a RAG system log for evaluation?"
    ),
]

response = llm.chat(messages)

print(response)

Streaming completion

import os
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

stream = llm.stream_complete(
    "List five checks for evaluating retrieval quality."
)

for token in stream:
    print(token.delta, end="", flush=True)

Streaming chat

import os
from llama_index.core.llms import ChatMessage
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

messages = [
    ChatMessage(role="user", content="Give a short RAG deployment checklist.")
]

stream = llm.stream_chat(messages)

for token in stream:
    print(token.delta, end="", flush=True)

Streaming improves perceived latency in chat interfaces and long answers. Not every wrapper exposes every provider-specific field in the same way. If your workflow needs DeepSeek reasoning_content, test the exact wrapper behavior before production.

Set DeepSeek as the Default LlamaIndex LLM

You can set DeepSeek as the global LlamaIndex LLM through Settings.llm. This is useful when query engines and indexes use the global setting.

import os
from llama_index.core import Settings
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

Settings.llm = llm

Global settings are convenient for examples and small projects. In production, explicit dependency injection can be safer because it avoids accidentally reusing an old global LLM across tests, notebooks, or services.

Working RAG Example with DeepSeek and LlamaIndex

This example loads local documents from ./data, configures a separate embedding model, builds a vector index, creates a query engine, asks a question, and prints source information.

import os
from llama_index.core import Settings, SimpleDirectoryReader, VectorStoreIndex
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5"
)

Settings.llm = llm
Settings.embed_model = embed_model

documents = SimpleDirectoryReader("./data").load_data()

index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine(
    similarity_top_k=4
)

response = query_engine.query(
    "What are the main risks mentioned in these documents?"
)

print("Answer:")
print(response)

print("\nSources:")
for source_node in response.source_nodes:
    print({
        "score": source_node.score,
        "metadata": source_node.node.metadata
    })

The embedding model in this example is separate from DeepSeek. It converts text chunks into vectors for retrieval. DeepSeek receives retrieved context and generates the final response. LlamaIndex does not automatically make answers correct; retrieval quality, source quality, chunking, and prompt design still matter.

Before using this in production, verify source chunks, evaluate retrieval quality, and test the workflow against realistic user questions. RAG can improve grounding when retrieval is good and sources are verified, but it does not eliminate hallucinations by itself.

Embeddings, Vector Stores, and Retrieval Quality

RAG quality depends heavily on retrieval. If the retriever selects weak or irrelevant chunks, the LLM may produce a weak answer even if the model is strong.

Tune these parts of the workflow:

• Embedding model: choose one that fits your language, domain, and document style.
• Chunk size: keep chunks large enough to preserve meaning but small enough for precise retrieval.
• Chunk overlap: use overlap when context spans boundaries, but avoid unnecessary duplication.
• Similarity top-k: retrieve enough context to answer the question without flooding the prompt.
• Metadata filters: filter by document type, date, department, project, author, or customer where useful.
• Reranking: add a reranker when initial vector search returns noisy matches.
• Prompt template: tell the model to answer only from retrieved context when source grounding matters.
• Source attribution: show file names, page numbers, document IDs, or metadata when possible.

DeepSeek generates the answer from retrieved context, but it cannot recover documents that retrieval did not select. Avoid sending entire private corpora in a prompt when retrieval would be safer, more relevant, and easier to audit.

Thinking Mode with LlamaIndex

DeepSeek supports thinking and non-thinking modes. In OpenAI format, the thinking toggle uses:

{"thinking": {"type": "enabled"}}

or:

{"thinking": {"type": "disabled"}}

DeepSeek also documents reasoning_effort values such as high and max. Thinking mode is useful for complex synthesis, harder reasoning, agent planning, and long-context analysis. Non-thinking mode is usually better for fast retrieval answers, extraction, classification, and routine summaries.

LlamaIndex wrapper support for passing provider-specific request fields can vary by version. If using LlamaIndex’s DeepSeek or OpenAILike wrappers, test whether additional_kwargs or another supported parameter forwards DeepSeek-specific request fields correctly.

# Test this in your installed LlamaIndex wrapper version before production.
# Provider-specific forwarding behavior can change by package version.

import os
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(
    model="deepseek-v4-pro",
    api_key=os.environ["DEEPSEEK_API_KEY"],
    additional_kwargs={
        "thinking": {
            "type": "enabled"
        },
        "reasoning_effort": "high"
    }
)

response = llm.complete(
    "Compare two migration plans and recommend the safer option."
)

print(response)

If reliable forwarding is not available, keep LlamaIndex for retrieval and call the DeepSeek API directly for the generation step. Do not claim that temperature, top_p, presence_penalty, or frequency_penalty control thinking-mode behavior. DeepSeek documentation states that these parameters do not affect thinking mode.

If you use tool calls in thinking mode, preserve required reasoning and tool-call fields according to the official DeepSeek documentation. Mishandling reasoning_content in a tool loop can break multi-turn tool workflows.

Structured Output and JSON

DeepSeek API supports JSON Output, but LlamaIndex has its own structured-output patterns, and provider-specific forwarding can vary by wrapper version. For DeepSeek JSON Output, the official API requires:

• response_format={"type":"json_object"}
• The word “json” in the system or user prompt.
• An example JSON shape.
• A reasonable max_tokens value.
• Backend parsing and validation.

For a full explanation, see DeepSeek JSON Output. In production, the most reliable pattern is often to let LlamaIndex retrieve the context, then call the DeepSeek API directly for strict JSON generation if the wrapper does not forward response_format reliably.

Direct DeepSeek API fallback after LlamaIndex retrieval

import json
import os
from openai import OpenAI
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings

Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5"
)

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
retriever = index.as_retriever(similarity_top_k=4)

nodes = retriever.retrieve(
    "Extract the top risks from the project documents."
)

context = "\n\n".join(
    node.node.get_content() for node in nodes
)

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

system_prompt = """
Return only valid json.

Use this JSON shape:
{
  "risks": [
    {
      "risk": "string",
      "severity": "low | medium | high",
      "source_note": "string"
    }
  ]
}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {
            "role": "user",
            "content": f"Use the following retrieved context and return json.\n\n{context}"
        }
    ],
    response_format={
        "type": "json_object"
    },
    max_tokens=1200,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    }
)

raw = response.choices[0].message.content or "{}"
parsed = json.loads(raw)

print(parsed)

This pattern keeps LlamaIndex responsible for retrieval and uses the official DeepSeek-compatible API path for strict JSON behavior. Always validate the parsed object before using it in downstream systems.

Tools, Agents, and Function Calling

DeepSeek API supports Tool Calls. Tool Calls let the model propose a function call; the application executes the tool and returns the result. The model does not directly execute shell commands, file operations, databases, emails, payments, network calls, or workflows.

LlamaIndex agent and tool support may not map perfectly to every DeepSeek provider-specific field. For tool-heavy, strict-schema, or thinking-mode tool-call workflows, test the wrapper carefully. If needed, combine LlamaIndex retrieval with a direct DeepSeek API call for the final tool-calling loop.

Follow these rules:

• Validate tool arguments before execution.
• Use allowlists for tools and actions.
• Require human approval for sensitive operations.
• Do not allow unrestricted shell, file, database, email, payment, or network access.
• Log tool decisions safely without exposing sensitive prompts or credentials.
• Do not overpromise strict mode through LlamaIndex unless you have tested it in the exact wrapper version.

For official DeepSeek tool-call behavior, see DeepSeek Tool Calls. For reasoning-specific behavior, see DeepSeek Thinking Mode.

TypeScript / JavaScript Note

LlamaIndex TypeScript documents DeepSeekLLM, but current TypeScript docs may show older model names. They also list limitations around function calling and json-output parameters. For that reason, this article focuses on Python.

For TypeScript production work, test current model names, streaming, JSON behavior, tools, and provider-specific parameters against the exact installed package version. For a broader JavaScript setup, read the DeepSeek Node.js TypeScript guide.

Context Caching, Token Usage, and Long Context

DeepSeek context caching is enabled by default. RAG systems may benefit from repeated prefixes, stable system prompts, repeated retrieved-context patterns, or repeated document instructions, but cache hits depend on official DeepSeek rules and request structure.

Do not promise fixed savings from caching. Inspect token usage fields and read the official documentation before making billing or architecture decisions. For supporting material, see DeepSeek Context Caching and DeepSeek Token Usage.

Even with long context, do not automatically send everything. Retrieval can still improve relevance, latency, auditability, and source control. A smaller set of high-quality retrieved chunks is often better than a very large prompt filled with marginally related text.

Where to Verify Current DeepSeek API Pricing

Because official API prices, billing categories, and promotions can change, this article does not publish static prices. For current public rates, always check the official DeepSeek Models & Pricing page.

For a site-level explanation that avoids copying live rates into every developer article, see the DeepSeek pricing guide.

Security Checklist for DeepSeek + LlamaIndex

• Store DEEPSEEK_API_KEY server-side.
• Do not hard-code keys in notebooks, repositories, scripts, Docker images, or demos.
• Do not expose keys in browser JavaScript, frontend bundles, public static pages, screenshots, shared notebooks, or logs.
• Use secret managers in production.
• Rotate keys immediately if exposed.
• Review what documents are indexed.
• Review what chunks are sent to the hosted API.
• Avoid logging full prompts if they contain sensitive data.
• Protect vector stores, document stores, indexes, and metadata.
• Validate tool arguments before execution.
• Use human approval for sensitive actions.
• Review privacy, legal, and compliance requirements for regulated data.

Common Errors and Fixes

Problem	Likely cause	Fix
401 authentication failure	Missing, wrong, expired, or exposed API key.	Check DEEPSEEK_API_KEY, rotate exposed keys, and confirm the key belongs to the DeepSeek account you intend to use.
402 insufficient balance or account billing issue	Account state does not allow the request.	Check the official account state and billing page. Do not rely on static article pricing.
422 invalid parameters	Wrong model name, unsupported field, invalid schema, or bad request shape.	Confirm the model ID, request body, JSON schema, and wrapper forwarding behavior.
429 rate limit	Too many requests or bursts beyond the allowed rate.	Add backoff, reduce concurrency, batch carefully, and monitor request volume.
500 or 503 server issue	Temporary provider-side or network issue.	Add timeouts, retries for safe operations, fallback behavior, and monitoring.
Wrapper rejects deepseek-v4-flash or deepseek-v4-pro	Installed LlamaIndex DeepSeek wrapper may not recognize current V4 model IDs.	Upgrade packages, check the wrapper version, use OpenAILike if appropriate, or call the DeepSeek API directly after retrieval.
LlamaIndex example uses old aliases	Documentation or sample code may still show older names.	Use deepseek-v4-flash or deepseek-v4-pro for new DeepSeek API examples.
JSON Output not forwarded	Wrapper version may not pass provider-specific fields exactly as expected.	Test additional_kwargs or use a direct DeepSeek API fallback for strict JSON generation.
Tool call loop fails	Missing tool message, invalid arguments, or mishandled reasoning/tool-call fields.	Validate arguments, preserve required fields, and compare the flow with official DeepSeek Tool Calls documentation.
RAG answer is irrelevant	Poor retrieval, weak embeddings, bad chunking, or noisy source data.	Tune chunk size, overlap, top-k, metadata filters, reranking, and prompt templates.
Embeddings missing or wrong	No embedding model configured, or an embedding model poorly matched to the corpus.	Configure embeddings explicitly and evaluate retrieval quality before judging the LLM.
API key exposed in notebook or repo	Hard-coded key or shared environment file.	Revoke or rotate the key, remove it from history where possible, and move secrets to a secure environment or secret manager.

Production Checklist

• Pin package versions.
• Confirm current DeepSeek model IDs.
• Test wrapper forwarding for DeepSeek-specific parameters.
• Configure embeddings explicitly.
• Tune chunking and retrieval.
• Add source attribution.
• Add observability and tracing.
• Validate JSON output.
• Validate tool arguments.
• Add retries and timeouts.
• Avoid blind retries for side-effect tools.
• Monitor token usage and latency.
• Review privacy and compliance.
• Keep a direct DeepSeek API fallback for provider-specific features if needed.

When Should You Use DeepSeek with LlamaIndex?

Use DeepSeek with LlamaIndex when:

• You need document Q&A.
• You need RAG over private or internal documents.
• You need a query engine or chat engine grounded in indexed content.
• You want DeepSeek as the generation model.
• You want LlamaIndex to manage loading, indexing, retrieval, and context assembly.
• You are building a knowledge-base assistant.
• You need source-aware answers.

It may not be a good fit when:

• You only need one simple model call.
• You do not need retrieval.
• Your workflow is mostly tool orchestration rather than data grounding.
• You need a TypeScript feature currently limited in LlamaIndex DeepSeek docs.
• Your organization has not approved sending retrieved content to the DeepSeek API.

FAQ