iflytek/astron-agent · error · ImportError

ragflow_sdk is not available

Error message

ragflow_sdk is not available

What it means

get_rag_object in core/knowledge/infra/ragflow/ragflow_client.py lazily constructs a cached RAGFlow SDK client. The `ragflow_sdk` package is imported defensively (RAGFlow may be None); if it was not installed and a RAGFlow client is requested, an ImportError('ragflow_sdk is not available') is raised rather than failing with a cryptic NameError.

Solutions

1. Install the optional dependency: pip install ragflow_sdk (or the project's ragflow extra)
2. Rebuild/redeploy the core/knowledge image with the ragflow dependency included
3. Verify the interpreter the service runs with actually has the package (pip show ragflow_sdk inside the container)
4. If RAGFlow is not needed, disable the RAGFlow-backed code path via configuration instead of calling it

Example fix

# before
pip install -r requirements.txt
# after
pip install -r requirements.txt ragflow_sdk  # or: pip install .[ragflow]

import importlib.util
def ragflow_sdk_installed() -> bool:
    return importlib.util.find_spec('ragflow_sdk') is not None

try:
    rag = get_rag_object()
except ImportError:
    logger.error('ragflow_sdk missing; install it or disable RAGFlow features')
    rag = None

When it happens

Trigger: Calling any RAGFlow-dependent function (upload_document_to_dataset, _upload_via_default_group, retrieval, dataset CRUD) in an environment where the ragflow_sdk optional dependency is not installed.

Common situations: Deploying core/knowledge without the ragflow extra (pip install without [ragflow]); slim Docker image excluding the SDK; requirement pin removed; venv mismatch where the service runs outside the intended environment.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• WORKFLOW_IMPORT_FAILED
• 8125
• 8118
• REPO_CREATE_RAGFLOW_FAILED
• Header mismatch! Expected headers: , Actual headers:

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/8fba10b29d115039. Report an issue: GitHub.

Appendix: source

Thrown at core/knowledge/infra/ragflow/ragflow_client.py:57

_config_cache = None
_session_cache = None
_session_config_key = None
_session_lock = asyncio.Lock()
_rag_object = None
_rag_object_config_key = None


def get_rag_object() -> Any:
    """
    Get or create RAGFlow client instance with proper configuration loading
    """
    global _rag_object, _rag_object_config_key
    base_url = _config_value("base_url", "RAGFLOW_BASE_URL", "")
    api_key = _config_value("api_token", "RAGFLOW_API_TOKEN", "")
    config_key = (base_url, api_key)
    if _rag_object is None or _rag_object_config_key != config_key:
        if RAGFlow is None:
            raise ImportError("ragflow_sdk is not available")

        if not base_url:
            raise ValueError("RAGFLOW_BASE_URL not configured in environment variables")
        if not api_key:
            raise ValueError(
                "RAGFLOW_API_TOKEN not configured in environment variables"
            )

        _rag_object = RAGFlow(api_key=api_key, base_url=base_url)
        _rag_object_config_key = config_key
        print(f"RAGFlow client initialized with base_url: {base_url}")

    return _rag_object


def _load_ragflow_config() -> Dict[str, Any]:
    """
    Load RAGFlow configuration from constants module (with caching)

View on GitHub (pinned to 5e758547a8)