Llama-Index Managed Llama Cloud Indices

0.11.1 · active · verified Sat Apr 11

This library provides integration for LlamaIndex to create, manage, and query indices hosted on Llama Cloud. It enables persistent, scalable, and production-ready Retrieval-Augmented Generation (RAG) solutions without needing to manage vector databases or other infrastructure directly. The current version is `0.11.1`, and it follows the frequent release cadence of the broader LlamaIndex ecosystem, often tied to Llama Cloud service updates.

Common errors

```
ModuleNotFoundError: No module named 'llama_index.indices.managed.llama_cloud'
```
cause The `llama-index-indices-managed-llama-cloud` package is not installed in your Python environment, or there is a conflict preventing its discovery. This can also occur if the import path has changed in newer LlamaIndex versions or if the package itself is deprecated.

fix Ensure the package is installed by running `pip install llama-index-indices-managed-llama-cloud`. If the issue persists, verify your Python environment. Note that this package is deprecated; consider migrating to `pip install llama-cloud` and updating your imports to `from llama_cloud_services import LlamaCloudIndex` for ongoing support.
```
{"error": "InvalidAPIKey", "message": "The provided API key is invalid or expired."}
```
cause The Llama Cloud API key used for authentication is either incorrect, expired, not properly configured as an environment variable (`LLAMA_CLOUD_API_KEY`), or lacks the necessary permissions. It could also be a mismatch with the target region or project scope.

fix Verify your API key in the Llama Cloud dashboard, generate a new one if it's expired or compromised, and ensure it's correctly set as an environment variable (e.g., `os.environ["LLAMA_CLOUD_API_KEY"] = "llx-..."`) or passed directly to the `LlamaCloudIndex` constructor (`api_key="llx-..."`). Also, confirm the API key's associated region and project.
```
pydantic.v1.error_wrappers.ValidationError: 1 validation error for ParsingModel[List[llama_cloud.types.pipeline.Pipeline]] __root__ -> 0 -> preset_retrieval_parameters -> retrieval_mode value is not a valid enumeration member; permitted: 'chunks', 'files_via_metadata', 'files_via_content'
```
cause This validation error indicates a mismatch between the `llama-index-indices-managed-llama-cloud` client library's expected data model for API responses (specifically regarding `retrieval_mode`) and what the Llama Cloud API is actually returning or accepting. This often happens due to version incompatibility between the client library and the Llama Cloud service or an outdated client.

fix Update the `llama-index-indices-managed-llama-cloud` package to its latest version (e.g., `pip install --upgrade llama-index-indices-managed-llama-cloud`) and ensure your `llama-index-core` packages are also up-to-date. If the issue persists, review the Llama Cloud documentation for the `retrieval_mode` parameter to align your code with the current API specifications.
```
NOTE: This package has been deprecated and is no longer maintained. Please use the llama-cloud package instead.
```
cause The `llama-index-indices-managed-llama-cloud` package has been deprecated by the LlamaIndex project. It is no longer actively maintained, and its functionality has been integrated into, or replaced by, the `llama-cloud` package to support the evolving Llama Cloud services.

fix To ensure continued support, access to new features, and bug fixes, migrate your application to use the `llama-cloud` package. First, uninstall the deprecated package (`pip uninstall llama-index-indices-managed-llama-cloud`), then install the new package (`pip install llama-cloud`). Update your import statements in your code, for example, from `from llama_index.indices.managed.llama_cloud import LlamaCloudIndex` to `from llama_cloud_services import LlamaCloudIndex`.

Warnings

gotcha The `LLAMA_CLOUD_API_KEY` environment variable or `api_key` parameter in `LlamaCloudIndex` initialization is mandatory for authentication with Llama Cloud. Forgetting to set it will result in authentication errors and prevent index operations.
Fix: Ensure `LLAMA_CLOUD_API_KEY` is set in your environment (e.g., `export LLAMA_CLOUD_API_KEY='your-key'`) or passed directly as `api_key='your-key'` to the `LlamaCloudIndex` constructor.
breaking The LlamaIndex ecosystem undergoes rapid development. Frequent updates in the core `llama-index` library can introduce API changes that might affect the `llama-index-indices-managed-llama-cloud` package. This can lead to breaking changes between minor versions.
Fix: It is highly recommended to pin the exact versions of both `llama-index` and `llama-index-indices-managed-llama-cloud` in your `requirements.txt` or `pyproject.toml` to ensure stability: `llama-index==x.y.z` and `llama-index-indices-managed-llama-cloud==a.b.c`.
gotcha When creating or connecting to an index, the `name` parameter in `LlamaCloudIndex` must be unique within your Llama Cloud project. If you call `from_documents` or `from_index_name` with an existing name, it will connect to that index. If new documents are provided, they will be upserted into the existing index, which might not be the intended behavior if you expect a fresh index.
Fix: Always use a distinct name for a truly new index. If you intend to update an existing index, explicitly pass `index_name` and handle document updates accordingly. Consider checking for index existence before creating if logic depends on it.

Install

pip install llama-index-indices-managed-llama-cloud Install package

Imports

LlamaCloudIndex

wrong:

from llama_index.readers.llama_cloud import LlamaCloudReader

correct:

from llama_index.indices.managed.llama_cloud import LlamaCloudIndex

LlamaCloudReader is for data ingestion, LlamaCloudIndex is for managing the index itself.

Quickstart

This quickstart demonstrates how to initialize a `LlamaCloudIndex`, optionally providing documents for ingestion, and then querying it. It assumes the `LLAMA_CLOUD_API_KEY` environment variable is set for authentication with Llama Cloud.

import os
from llama_index.indices.managed.llama_cloud import LlamaCloudIndex
from llama_index.core.schema import Document

# Set your Llama Cloud API key as an environment variable
# You can obtain one from app.llamacloud.ai
api_key = os.environ.get("LLAMA_CLOUD_API_KEY", "")
if not api_key:
    print("Warning: LLAMA_CLOUD_API_KEY environment variable not set. The example will not fully function without it.")

# Define some documents to be indexed
documents = [
    Document(text="The quick brown fox jumps over the lazy dog."),
    Document(text="LlamaIndex helps build LLM applications with external data.")
]

# Create a new managed index or connect to an existing one by name.
# If the index 'my_managed_index_example' doesn't exist, it will be created.
# If it exists, the documents will be upserted.
print(f"Attempting to create/connect to Llama Cloud Index 'my_managed_index_example'...")
index = LlamaCloudIndex.from_documents(
    documents,
    name="my_managed_index_example", # Use a unique name for your index
    api_key=api_key
)
print(f"Successfully connected to Llama Cloud Index: {index.index_name}")

# Query the index using a query engine
query_engine = index.as_query_engine()
query_text = "What does LlamaIndex help with?"
print(f"\nQuery: {query_text}")
response = query_engine.query(query_text)
print(f"Response: {response}")

view raw JSON →