如何使用DeepSeek配合LlamaIndex进行RAG（V4教程）

您有一个PDF文件夹、一个DeepSeek API密钥和一个问题：如何让LlamaIndex使用DeepSeek而不是OpenAI来回答关于您的文档的问题？本教程将指导您在当前V4 API上从`pip install`开始，到构建一个可以检索片段、调用`deepseek-v4-flash`并流式传输答案的工作查询引擎的端到端过程。我们将涵盖官方`llama-index-llms-deepseek`包、更灵活的`OpenAILike`路径、在V4-Flash和V4-Pro之间的模型选择、思考模式、嵌入选择（因为DeepSeek不提供嵌入模型），以及传统的`deepseek-chat`/`deepseek-reasoner`迁移窗口。代码示例适用于Python 3.10+。

What you’ll build

一个最小但适合生产的检索增强生成管道：加载文档目录，将它们分块并嵌入到向量存储中，检索与用户查询最相关的段落，并通过LlamaIndex将它们传递给DeepSeek V4。最终，您将拥有一个可以回答您自己数据中问题的脚本，并清楚地了解如何选择DeepSeek模型层级以及在需要推理时如何开启思考模式。

存在两种集成路径。第一种使用专门的 llama-index-llms-deepseek 包，它 继承了 LlamaIndex 的 OpenAILike 类。第二种直接使用 OpenAILike 。两者都击中相同的端点—— POST /chat/completions, the OpenAI-compatible surface at https://api.deepseek.com ——所以选择主要取决于用户体验。以下是两者的代码片段。

Prerequisites

• Python 3.10 或更高版本，在虚拟环境中。
• 一个 DeepSeek API 密钥。如果您还没有，请参阅 get a DeepSeek API key.
• 一个嵌入模型提供者。DeepSeek目前不提供嵌入模型，因此您需要使用OpenAI的 text-embedding-3-small，一个本地模型（BGE、Jina或类似模型，通过Hugging Face获取），或Ollama-served嵌入。
• LlamaIndex安装需要约200MB的磁盘空间，如果使用本地嵌入则需要更多。
• 熟悉LlamaIndex的基本知识——如果不熟悉，请阅读 DeepSeek Python integration first.

选择一个模型：V4-Flash 或 V4-Pro

DeepSeek V4（发布于2026年4月24日）以两个MIT许可下的开放权重专家混合模型的形式发布： deepseek-v4-flash （总参数量284B / 活跃参数量13B）和 deepseek-v4-pro （总容量1.6T / 活跃容量49B）。两者共享一个100万个token的默认上下文窗口，并支持输出高达384,000个token。两者通过相同的参数支持思考模式——它不是一个单独的模型ID。

对于大多数RAG工作负载， deepseek-v4-flash 是正确的默认设置。每百万token的输出成本大约比V4-Pro便宜12倍，延迟更低，并且从上下文合成的任务很少能从前沿级别的推理中受益。当检索到的上下文包含代码、密集的财务表格或多文档推理链（在此情况下，Flash的表现不足）时，请选择V4-Pro。

2026年4月的价格；请在官方网站上核实 DeepSeek API pricing page before committing.

一个注意事项：如果您正在维护一个仍然使用 deepseek-chat or deepseek-reasoner的旧脚本， deepseek-v4-flash. They retire on 2026-07-24 at 15:59 UTC; migrating is a one-line model= change. The base_url stays the same.

步骤 1：安装软件包

使用专门的DeepSeek包装器，加上一个向量存储和一个嵌入提供者。shell命令安装LlamaIndex核心、DeepSeek LLM包、OpenAI嵌入（在此处仅用于嵌入文本）和文件读取器：

pip install llama-index-core
pip install llama-index-llms-deepseek
pip install llama-index-embeddings-openai
pip install llama-index-readers-file

如果您希望完全避免使用OpenAI，可以将第三行替换为 llama-index-embeddings-huggingface 并使用本地模型，例如 BAAI/bge-small-en-v1.5。这将在您的硬件上保留嵌入，唯一的出站流量就是DeepSeek调用本身。

步骤 2：配置 DeepSeek LLM

专用包为您提供 DeepSeek 类 that 扩展 OpenAILike 并且接受一个 model plus api_key将设置设置为全局 设置s 对象，因此脚本中的每个检索器和查询引擎默认使用DeepSeek。Python：

import os
from llama_index.core import 设置s
from llama_index.llms.deepseek import DeepSeek
from llama_index.embeddings.openai import OpenAIEmbedding

设置s.llm = DeepSeek(
    model="deepseek-v4-flash",
    api_key=os.environ["DEEPSEEK_API_KEY"],
    temperature=1.3,           # general conversation default
    max_tokens=2048,
)
设置s.embed_model = OpenAIEmbedding(
    model="text-embedding-3-small",
    api_key=os.environ["OPENAI_API_KEY"],
)

The temperature 数值遵循DeepSeek官方指南： 0.0 for code or maths, 1.0 for data analysis, 1.3 用于一般对话和翻译 1.5 用于创意写作。选择与您的检索任务相匹配的值；对于基于事实的RAG在技术文档上的应用， 0.0 减少漂移。参见更广泛的参数讨论。 DeepSeek prompt engineering.

替代方案：直接使用 OpenAI 进行配置

如果您不想使用第二个包，请指向 OpenAILike 在DeepSeek的基础URL上。这是专用包装器内部使用的相同代码路径：

from llama_index.llms.openai_like import OpenAILike

设置s.llm = OpenAILike(
    model="deepseek-v4-flash",
    api_base="https://api.deepseek.com/v1",
    api_key=os.environ["DEEPSEEK_API_KEY"],
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=1_000_000,
    max_tokens=2048,
)

设置 is_chat_model=True 事项 — 没有它，LlamaIndex 将通过遗留的完成路径路由，并且元数据推断会中断。 is_function_calling_model=True 启用工具调用功能，V4 支持在思维和非思维模式下进行。对于更底层的细节，参考文档是开始的地方。如果你更喜欢从 Anthropic SDK 驱动它，DeepSeek 还暴露了一个与 Anthropic 兼容的界面，该界面使用相同的基 URL。 DeepSeek OpenAI SDK compatibility ) 然后构建一个向量索引。API 是无状态的 — LlamaIndex 在每个请求时发送会话历史和检索到的上下文，因为 DeepSeek 不会在服务器端保留之前的回合。

步骤 3：构建索引

将源文件拖入一个 data/ 目录（PDF文件、Markdown、HTML、.txt、.docx文件均由对于更深入的chunking策略、混合检索和针对DeepSeek的重新排序的探讨，该文档读取） 对于更深入的chunking策略、混合检索和针对DeepSeek的重新排序的探讨，该文档将索引包装在查询引擎中并提出一个问题。检索器拉取 top-k 块，LlamaIndex 将它们放入提示中，DeepSeek 综合出一个答案。Python：

from llama_index.core import 对于更深入的chunking策略、混合检索和针对DeepSeek的重新排序的探讨，该文档, VectorStoreIndex

documents = 对于更深入的chunking策略、混合检索和针对DeepSeek的重新排序的探讨，该文档("data").load_data()
index = VectorStoreIndex.from_documents(documents)
index.storage_context.persist(persist_dir="./storage")

介绍了架构选择。这里的最低路径足以实现一个工作原型。 DeepSeek RAG tutorial 流式传输只需更改一个标志——设置

步骤 4：查询索引

. 这提供了逐个标记的输出，使得面向用户的聊天 UI 感觉响应。对于更深入的流式参考，请参阅

query_engine = index.并迭代(similarity_top_k=4)
response = query_engine.query(
    "Summarise the refund policy in three bullet points."
)
print(response)

并迭代 并迭代 on 并迭代 docs. docs.. DeepSeek API streaming docs.

步骤 5：开启思考模式（实际需要时）

V4中的思考模式是一个请求参数，而不是一个独立的模型ID。要通过LlamaIndex开启它，请传递 reasoning_effort and the thinking 将extra-body标志传递到底层客户端。 DeepSeek 使用专用包装器：

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

With thinking enabled, the response returns reasoning_content alongside the final content. LlamaIndex在对于最高设置（您需要≥384,000以避免在非常长的跟踪上截断）。中呈现最终内容 对于最高设置（您需要≥384,000以避免在非常长的跟踪上截断）。；如果需要记录或显示推理跟踪，则可在底层消息对象上找到推理跟踪。使用 reasoning_effort="max" 假设一个面向客户支持的RAG应用每月运行100,000次查询 max_tokens 以确保缓存命中。

一个实用规则：对于涉及检索文档的多步推理查询（法律交叉引用、财务核对、多跳研究）启用思考模式，而对于检索和总结任务则关闭它。思考模式响应成本更高——您需要为推理令牌付费。对于更深入的比较，请参阅 DeepSeek R1 vs OpenAI o1.

步骤 6：成本计算示例

在您认为集成完成之前进行三项检查： deepseek-v4-flash。一个典型请求：1,500个令牌的系统提示（首次调用后缓存），400个令牌的检索上下文加上100个令牌的用户查询（未缓存），以及250个令牌的回答。在V4-Flash速率下列出所有三个桶：

Cached input    : 1,500 × 100,000 = 150,000,000 × $0.0028/M = $4.20
Uncached input  :   500 × 100,000 =  50,000,000 × $0.14/M  = $7.00
Output          :   250 × 100,000 =  25,000,000 × $0.28/M  = $7.00
                                                              ------
Total                                                          $18.20

在V4-Pro速率下（每百万$0.0145 / $1.74 / $3.48列表，有效$0.003625 / $0.435 / $0.87，通过2026-05-31的75%促销期间），同样的工作量约为$195——大约高11倍。选择与您质量阈值匹配的层级；对于基于事实的RAG，Flash通常在每可接受回答的价格上更具优势。The DeepSeek pricing calculator 自动处理任意令牌混合。请注意，只有当LlamaIndex实际重用前缀时，上下文缓存才会启动——请将系统提示和工具模式保持在系统提示的开头。 messages 确认请求击中DeepSeek。

Verify it worked

Three checks before you call the integration done:

1. Confirm the request hits DeepSeek. Set llama_index.core.set_global_handler("simple") 或者使用HTTP调试代理包装，并确认URL是 https://api.deepseek.com/v1/chat/completions.
2. 确认检索到的上下文在提示中。 打印 response.source_nodes ——你应该看到为问题检索到的块。
3. 确认思考模式（如果已启用）。 延迟明显增加，并且底层响应对象包含非空 reasoning_content.

Common errors and fixes

Next steps

您有一个基于DeepSeek的RAG管道正在运行。合理的扩展：

• Swap VectorStoreIndex 对于托管向量数据库（Qdrant、Weaviate、Pinecone），一旦您的语料库超过内存。
• 在LLM调用之前添加跨编码的重排序 —— 它几乎总是优于提高 similarity_top_k.
• 与LangChain的等效功能进行比较 DeepSeek with LangChain 如果您的团队已经标准化使用LangChain。
• 如果您希望将所有内容都从公共互联网上移除，请指向一个运行着开放DeepSeek权重的本地Ollama服务器——参见 OpenAILike 浏览我们其他 running DeepSeek on Ollama.
• 以获取端到端应用程序构建。 DeepSeek tutorials ，配置一个嵌入模型（DeepSeek不提供），并从您的文档中构建一个

DeepSeek AI Guide is an independent resource and is not affiliated with DeepSeek or its parent company. Model IDs, pricing and API behaviour change; check the official DeepSeek documentation and pricing page before committing to a production decision.