1.5 环境搭建与基础使用入门

1.5 环境搭建与基础使用入门

本节摘要：本节完成从零到第一答的实操：虚拟环境与包安装（主包加按需集成包的"乐高式"安装策略）、API Key 配置、第一个索引与第一问第一答、第一个聊天引擎，以及五个最高频的新手报错与解法。读完你有一个可继续使用的实验台，后面各章都在它上面动手术。

安装策略：主包很小，集成按需

LlamaIndex 采用模块化分发：主包 llama-index-core 只含核心抽象，任何具体能力（某家模型、某种连接器）都是独立的集成包。对新手，元包 llama-index 等价于"core + OpenAI 默认件"，装它最省事；对生产，建议按需安装集成包，避免拖入几十个不用的依赖。

# 方案一：新手快速起步（元包，自带 OpenAI 默认件）
pip install llama-index

# 方案二：生产按需安装（示例：本地模型 + 本地嵌入 + 本地向量库）
pip install llama-index-core llama-index-llms-ollama \
    llama-index-embeddings-huggingface \
    llama-index-vector-stores-chroma
​

包名规律：llama-index-<类别>-<产品>，如 llama-index-readers-file（文件读取）、llama-index-llms-openai-like（OpenAI 兼容接口，国内模型服务多走它）。忘了包名时，按这个规律拼，命中率极高。

Key 与模型配置

# 最常见：环境变量方式（不要把 Key 写进代码仓库）
import os
os.environ["OPENAI_API_KEY"] = "sk-..."   # 实际项目用 .env 加载

# 国内 OpenAI 兼容服务的写法
from llama_index.llms.openai_like import OpenAILike
from llama_index.core import Settings

llm = OpenAILike(
    model="qwen-plus",
    api_base="https://dashscope.example-compatible-endpoint/v1",
    api_key=os.environ["DASHSCOPE_API_KEY"],
    is_chat_model=True,
)
Settings.llm = llm
Settings.embed_model = OpenAILikeEmbedding(...)   # 嵌入模型同理换掉默认
​

⚠️ 常见坑：不配任何 Key 直接跑官方示例，默认会尝试调用 OpenAI 且需要联网。若你打算全程本地模型，第一步就是把 Settings.llm 与 Settings.embed_model 都换成本地实现，否则示例在"建索引"阶段就会因默认嵌入模型要联网而报 401。

第一问第一答

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 准备：在 data 子目录放几篇自己的 txt 或 pdf 文档
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents, show_progress=True)

query_engine = index.as_query_engine()
response = query_engine.query("这份文档的核心结论是什么？")
print(response)

# 出处检查：看答案引用了哪些节点
for node_id, node in response.source_nodes.items() if hasattr(response.source_nodes, "items") else enumerate(response.source_nodes):
    print(node.score, node.metadata.get("file_name"), node.get_content()[:60])
​

from_documents 一次完成了分块、嵌入、内存索引三件事；数据量大时建议改用 insert 增量插入或外接向量库（3.4 节）。第一次运行会下载默认嵌入模型文件，属正常现象。

从问答到对话

# 聊天引擎：带记忆，会改写指代（"它呢？""再来一个"）
chat_engine = index.as_chat_engine(mode="condense_question")
print(chat_engine.chat("年假可以拆分使用吗？"))
print(chat_engine.chat("那病假呢？"))   # "那病假呢"会被改写成完整问题再检索
​

condense_question 模式把口语化的追问连同历史压缩成独立完整的问题再走检索——这就是聊天引擎与查询引擎的本质区别。

新手五大报错速查

一是 No module named 'llama_index.llms...'：说明用了集成包但没装，按包名规律补装。二是 401/网络错误：默认 OpenAI 件在要 Key 或联网，换成本地件或配好 Key。三是 context window exceeded：召回内容太多超过模型窗口，调小 similarity_top_k 或 chunk_size，并检查 Settings.context_window 是否设对（窗口设大了框架不会主动保护你）。四是 PDF 读出乱码或空文本：扫描件没有文字层，需要先走 OCR，普通 PDF 解析可考虑换更强调 PDF 的读取方案。五是重复建索引每次都要嵌入很慢：默认索引在内存、进程退出即失，学 3.4 节的持久化（storage_context.persist）后再别重复付嵌入的钱。

本节要点回顾

• 乐高式安装：core 很小，集成按 llama-index-类别-产品 规律按需装；新手装元包最快。
• 本地化第一步：用本地件时先换掉 Settings 的 llm 与 embed_model 两个默认值。
• 三行起步：读文档 → from_documents → as_query_engine，背后六决策后续章节逐一拆改。
• 两种引擎：query 一次性、chat 带记忆并做问题压缩改写。
• 五报错：缺包、401、超窗、扫描 PDF、重复嵌入——都能在三十秒内定位。