1. 启动 llama.cpp 服务器
使用 llama.cpp 二进制文件启动一个兼容 OpenAI API 的服务器。
bash
./server -m /path/to/your/model.gguf --host 127.0.0.1 --port 8080 -c 4096
2. 在 LlamaIndex 中连接服务器
实例化 LlamaCPP 时，将 model_url 指向本地服务器地址，并忽略 model_path。
python
llm = LlamaCPP(
model_url="http://127.0.0.1:8080", # 指向正在运行的服务器
temperature=0.1,
max_new_tokens=512,
context_window=4096,
model_kwargs={}, # 服务器模式下无需指定加载参数
messages_to_prompt=messages_to_prompt,
completion_to_prompt=completion_to_prompt,
)
关键配置与避坑指南
-
上下文窗口（
context_window） ：这是最容易出错的配置。必须与模型实际支持的上下文长度以及启动服务器时的-c参数保持一致，否则 LlamaIndex 可能会静默截断你的提示词或文档内容。 -
GPU 加速 ：确认 GPU 是否生效。如果日志中看到
offloaded 29/29 layers to GPU之类的信息，则表示加速成功。若未生效，请检查llama-cpp-python是否在编译时启用了正确的后端（CUDA/Metal/CLBlast）。 -
提示词模板 ：不同模型（如 Llama 2、Zephyr、Qwen）需要特定的提示词格式。
llama_index.llms.llama_cpp.llama_utils中提供了messages_to_prompt和completion_to_prompt工具函数，务必根据你的模型进行适配。 -
性能调优 ：在生产环境中，可以调整索引的
chunk_overlap和检索的similarity_top_k来平衡延迟与准确性。 -
版本兼容性 ：注意
llama-cpp-python与llama-index-llms-llama-cpp插件的版本匹配。0.1.79 版本之后，模型格式已从 GGML 转向 GGUF，请确保使用的模型文件格式正确。