LlamaIndex 新版本中 VectorStoreIndex 用法变更了哪里？

LlamaIndex 新版本（v0.10.x 及以上）中，VectorStoreIndex 用法主要变更在导入路径迁移至 llama_index.core、ServiceContext 配置对象被 Settings 全局配置替代，以及 GPTVectorStoreIndex 等旧类统一合并为 VectorStoreIndex。开发者需更新导入语句并调整配置方式，否则代码会报错或触发弃用警告。

先说结论：升级至 v0.10.x 后，VectorStoreIndex 核心逻辑未变，但配置方式和导入路径发生结构性调整，必须修改代码才能正常运行。

适合：正在从 LlamaIndex 0.9.x 或更早版本迁移到 0.10.x 及以上的项目。
重点看：导入路径从 llama_index 改为 llama_index.core，ServiceContext 被 Settings 取代。
别忽略：旧类名 GPTVectorStoreIndex 已废弃，直接使用 VectorStoreIndex 即可。

命令速用版

如果项目依赖包版本已更新，直接使用以下命令检查并升级代码结构，确保核心模块安装正确。

pip install llama-index-core
pip install llama-index-embeddings-openai
pip install llama-index-llms-openai

代码导入修正示例，将旧版导入路径替换为新版本标准路径。

# 旧版写法（已弃用）
from llama_index import VectorStoreIndex, ServiceContext

# 新版写法（推荐）
from llama_index.core import VectorStoreIndex, Settings

为什么会这样

LlamaIndex v0.10.x 版本进行了架构重构，目的是解耦核心功能与集成插件，提升模块化程度。

此前 VectorStoreIndex 依赖 ServiceContext 传递全局配置，新版本改为通过 Settings 对象全局管理或直接在接口中传递参数。GPTVectorStoreIndex 和 GPTSimpleVectorIndex 等特定模型绑定的类被统一为通用的 VectorStoreIndex，底层通过 vector_store 参数集成不同向量数据库。这种变化减少了类冗余，但要求开发者显式配置嵌入模型和 LLM 对象。

分步处理

按照以下步骤修改代码，确保 VectorStoreIndex 在新版本中正常工作。

步骤 1：更新导入路径

检查所有 Python 文件，将 llama_index 根目录下的导入改为 llama_index.core。LLM 和嵌入模型需从对应集成包导入。

LlamaIndex 新版本中 VectorStoreIndex 用法变更了哪里？

from llama_index.core import VectorStoreIndex, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

步骤 2：迁移配置对象

删除 ServiceContext 初始化代码，改用 Settings 全局配置或在索引构建时直接传入模型对象。

# 旧版配置
# service_context = ServiceContext.from_defaults(llm=llm, embed_model=embed_model)

# 新版配置
Settings.llm = OpenAI(model="gpt-3.5-turbo")
Settings.embed_model = OpenAIEmbedding()

步骤 3：构建索引

使用 from_documents 方法构建索引，无需显式传递 service_context。

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

步骤 4：调整参数名称

检查是否有 max_input_size 参数，新版已改为 context_window，且在 Settings 中配置。

Settings.context_window = 4096

怎么验证是否生效

运行脚本后观察控制台输出，确认无 DeprecationWarning 弃用警告，且查询能返回正常结果。

检查点 1：无报错

代码运行不抛出 ImportError 或 AttributeError，特别是关于 ServiceContext 未找到的错误。

检查点 2：无警告

控制台不显示 ServiceContext is deprecated 或 GPTVectorStoreIndex is deprecated 相关警告信息。

检查点 3：查询响应

执行 query_engine.query 测试查询，确认能返回文本响应而非空对象或异常。

常见坑

迁移过程中容易遇到以下问题，需提前排查。

坑 1：混合导入导致冲突

部分文件使用旧版导入，部分使用新版，会导致对象类型不匹配。建议全局搜索 from llama_index import 并统一替换。

坑 2：缺少集成包

新版将嵌入模型和 LLM 拆分为独立包，仅安装 llama-index-core 无法使用 OpenAI 模型，需额外安装 llama-index-llms-openai 等依赖。

坑 3：持久化路径变更

索引持久化存储的接口略有调整，若使用 index.storage_context.persist()，需确认路径权限和序列化格式兼容性。

常见问题

GPTVectorStoreIndex 还能用吗？

不能继续使用，该类已在新版本中废弃，需直接改用 VectorStoreIndex 并配置对应的嵌入模型。

ServiceContext 报错找不到怎么办？

ServiceContext 已被弃用，请删除相关代码，改用 Settings 对象全局配置 LLM 和嵌入模型参数。

旧版索引数据需要重建吗？

向量数据本身通常兼容，但索引元数据结构可能变化，建议重新构建索引以确保与新版本检索器兼容。

max_input_size 参数去哪里了？

该参数已更名为 context_window，请在 Settings 对象中设置 Settings.context_window 而非传递给索引构造函数。

参考来源

LlamaIndex v0.10.0 迁移指南（关于导入变更和 ServiceContext 弃用说明）
探索 LlamaIndex 中的最新变化与 API 使用（关于 VectorStoreIndex 统一和参数变更）
LlamaIndex 0.10.x 版本大升级，这些变化你不能错过（关于版本升级带来的结构变化）
llamaindex 使用向量存储索引 (VectorStoreIndex)（关于基本用法和参数配置）