使用Hugging Face构建LLAMA向量索引时遇model_name参数必填错误

问题情况 #

• 使用Llama Index对接Hugging Face构建向量索引时，框架默认调用OpenAI服务，而非指定的Hugging Face模型
• 已显式定义mistralai/Mixtral-8x7B-Instruct-v0.1模型，尝试配置服务上下文后仍无效
• 执行代码时抛出ValueError: The model_name argument must be provided错误，手动添加参数后问题依旧

核心原因 #

问题出在未将自定义的Hugging Face LLM绑定到Llama Index的全局配置或索引构建上下文，导致框架仍尝试使用默认的OpenAI配置，而OpenAI相关参数未被正确设置。

解决方案 #

方法1：使用全局Settings配置（Llama Index v0.9+推荐） #

通过全局Settings统一指定LLM和嵌入模型，确保所有组件都使用自定义配置而非默认值：

import os
from huggingface_hub import login
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Settings
from llama_index.llms.huggingface import HuggingFaceInferenceAPI

# 加载文档
reader = SimpleDirectoryReader(input_files=["acquisition2.csv"])
documents = reader.load_data()

# 配置Hugging Face Token
HF_TOKEN = "XXXXXXX"
os.environ["HF_TOKEN"] = HF_TOKEN
login(token=HF_TOKEN)

# 全局配置LLM和嵌入模型
Settings.llm = HuggingFaceInferenceAPI(
    model_name="mistralai/Mixtral-8x7B-Instruct-v0.1", 
    token=HF_TOKEN
)
Settings.embed_model = "local"  # 使用本地嵌入模型，避免调用OpenAI嵌入接口

# 构建向量索引
index = VectorStoreIndex.from_documents(documents)

方法2：使用ServiceContext（旧版本兼容） #

如果使用Llama Index v0.9之前的版本，可通过ServiceContext传递配置：

import os
from huggingface_hub import login
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, ServiceContext
from llama_index.llms.huggingface import HuggingFaceInferenceAPI

reader = SimpleDirectoryReader(input_files=["acquisition2.csv"])
documents = reader.load_data()

HF_TOKEN = "XXXXXXX"
os.environ["HF_TOKEN"] = HF_TOKEN
login(token=HF_TOKEN)

llm = HuggingFaceInferenceAPI(
    model_name="mistralai/Mixtral-8x7B-Instruct-v0.1", 
    token=HF_TOKEN
)

# 创建服务上下文
service_context = ServiceContext.from_defaults(
    llm=llm,
    embed_model="local"
)

# 传入服务上下文构建索引
index = VectorStoreIndex.from_documents(documents, service_context=service_context)

额外注意事项 #

• 确保安装的Llama Index版本与代码兼容，建议使用最新稳定版
• 若embed_model="local"仍有问题，可指定具体的Hugging Face嵌入模型，例如embed_model="BAAI/bge-small-en-v1.5"
• 检查环境变量中是否残留OpenAI相关密钥，避免框架误调用

内容的提问来源于stack exchange，提问作者Goeast