配置

src.retrieval.cg_rag_config 负责读取 CG_RAG HTTP/MCP 路径、生成模型、超时、候选条文数量、检索缓存、generation streaming 和 hydration sidecar 参数。环境变量优先使用 CG_RAG_*，并保留 QUESTION_GENERATED_APP_* 兼容名称。远端部署可先由 QUESTION_APP_CONFIG / QUESTION_APP_SECRETS_CONFIG 映射出这些环境变量。

retrieve cache 的容量和 TTL 仍由配置控制，但缓存 key 会额外使用当前 profile fingerprint。fingerprint 来自运行时 profile、语料/索引摘要和 embedding/rerank 配置，不需要单独配置。

cg_rag_config

CgRagConfig dataclass

源代码位于： src/retrieval/cg_rag_config.py

@dataclass(frozen=True)
class CgRagConfig:
    http_prefix: str = "/cg-rag"
    mcp_path: str = "/cg-rag/mcp"
    llm_provider: str = "deepseek"
    generation_endpoint: str = ""
    generation_model: str = ""
    api_key: str = ""
    generation_response_format_json: bool = True
    generation_enable_thinking: bool = False
    generation_streaming: bool = True
    stream_answer_token_delay_seconds: float = DEFAULT_STREAM_ANSWER_TOKEN_DELAY_SECONDS
    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
    max_context_docs: int = DEFAULT_MAX_CONTEXT_DOCS
    default_max_items: int = DEFAULT_MAX_ITEMS
    cache_max_entries: int = DEFAULT_CACHE_MAX_ENTRIES
    cache_ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS
    hydration_sidecar_enabled: bool = True
    hydration_sidecar_path: str = ""
    generation_concurrency: int = DEFAULT_GENERATION_CONCURRENCY
    retrieval_concurrency: int = DEFAULT_RETRIEVAL_CONCURRENCY
    capacity_wait_timeout_seconds: float = DEFAULT_CAPACITY_WAIT_TIMEOUT_SECONDS
    # Vision is a separate upstream from the text generation above: hazard
    # identification needs a VLM, and deployments typically point the two at
    # different providers. Leaving these blank disables the vision endpoints
    # without affecting retrieval or text generation.
    vision_endpoint: str = ""
    vision_model: str = ""
    vision_api_key: str = ""
    vision_enable_thinking: bool = False
    vision_streaming: bool = True
    vision_max_images: int = DEFAULT_VISION_MAX_IMAGES
    vision_max_image_bytes: int = DEFAULT_VISION_MAX_IMAGE_BYTES
    vision_max_tokens: int = DEFAULT_VISION_MAX_TOKENS
    vision_agentic_max_search_rounds: int = DEFAULT_VISION_AGENTIC_MAX_SEARCH_ROUNDS
    vision_agentic_retrieval_topk: int = DEFAULT_VISION_AGENTIC_RETRIEVAL_TOPK

    @property
    def generation_configured(self) -> bool:
        return bool(self.generation_endpoint and self.generation_model)

    @property
    def vision_configured(self) -> bool:
        return bool(self.vision_endpoint and self.vision_model)

    @property
    def effective_vision_api_key(self) -> str:
        """Falls back to the text key so a single-gateway deployment only
        configures one credential."""

        return self.vision_api_key or self.api_key

effective_vision_api_key: str property

Falls back to the text key so a single-gateway deployment only configures one credential.

load_cg_rag_config() -> CgRagConfig

源代码位于： src/retrieval/cg_rag_config.py

def load_cg_rag_config() -> CgRagConfig:
    load_env_file()
    return CgRagConfig(
        http_prefix=_clean_path(
            _env_str("CG_RAG_HTTP_PREFIX", "QUESTION_GENERATED_APP_HTTP_PREFIX", "/cg-rag"),
            "/cg-rag",
        ),
        mcp_path=_clean_path(
            _env_str("CG_RAG_MCP_PATH", "QUESTION_GENERATED_APP_MCP_PATH", "/cg-rag/mcp"),
            "/cg-rag/mcp",
        ),
        llm_provider=_normalize_llm_provider(
            _env_str("CG_RAG_LLM_PROVIDER", "QUESTION_GENERATED_APP_LLM_PROVIDER", "deepseek")
        ),
        generation_endpoint=_env_str(
            "CG_RAG_GENERATION_ENDPOINT",
            "QUESTION_GENERATED_APP_GENERATION_ENDPOINT",
            "",
        ),
        generation_model=_env_str(
            "CG_RAG_GENERATION_MODEL",
            "QUESTION_GENERATED_APP_GENERATION_MODEL",
            "",
        ),
        api_key=_env_str("CG_RAG_API_KEY", "QUESTION_GENERATED_APP_API_KEY", ""),
        generation_response_format_json=_env_bool(
            "CG_RAG_GENERATION_RESPONSE_FORMAT_JSON",
            "QUESTION_GENERATED_APP_GENERATION_RESPONSE_FORMAT_JSON",
            True,
        ),
        generation_enable_thinking=_env_bool(
            "CG_RAG_GENERATION_ENABLE_THINKING",
            "QUESTION_GENERATED_APP_GENERATION_ENABLE_THINKING",
            False,
        ),
        generation_streaming=_env_bool(
            "CG_RAG_GENERATION_STREAMING",
            "QUESTION_GENERATED_APP_GENERATION_STREAMING",
            True,
        ),
        stream_answer_token_delay_seconds=_env_non_negative_float(
            "CG_RAG_STREAM_ANSWER_TOKEN_DELAY_SECONDS",
            "QUESTION_GENERATED_APP_STREAM_ANSWER_TOKEN_DELAY_SECONDS",
            DEFAULT_STREAM_ANSWER_TOKEN_DELAY_SECONDS,
        ),
        timeout_seconds=_env_float(
            "CG_RAG_TIMEOUT_SECONDS",
            "QUESTION_GENERATED_APP_TIMEOUT_SECONDS",
            DEFAULT_TIMEOUT_SECONDS,
        ),
        max_context_docs=_env_positive_int(
            "CG_RAG_MAX_CONTEXT_DOCS",
            "QUESTION_GENERATED_APP_MAX_CONTEXT_DOCS",
            DEFAULT_MAX_CONTEXT_DOCS,
        ),
        default_max_items=_env_positive_int(
            "CG_RAG_DEFAULT_MAX_ITEMS",
            "QUESTION_GENERATED_APP_DEFAULT_MAX_ITEMS",
            DEFAULT_MAX_ITEMS,
        ),
        cache_max_entries=_env_non_negative_int(
            "CG_RAG_RETRIEVE_CACHE_MAX_ENTRIES",
            "QUESTION_GENERATED_APP_RETRIEVE_CACHE_MAX_ENTRIES",
            DEFAULT_CACHE_MAX_ENTRIES,
        ),
        cache_ttl_seconds=_env_non_negative_float(
            "CG_RAG_RETRIEVE_CACHE_TTL_SECONDS",
            "QUESTION_GENERATED_APP_RETRIEVE_CACHE_TTL_SECONDS",
            DEFAULT_CACHE_TTL_SECONDS,
        ),
        hydration_sidecar_enabled=_env_bool(
            "CG_RAG_HYDRATION_SIDECAR_ENABLED",
            "QUESTION_GENERATED_APP_HYDRATION_SIDECAR_ENABLED",
            True,
        ),
        hydration_sidecar_path=_env_str(
            "CG_RAG_HYDRATION_SIDECAR_PATH",
            "QUESTION_GENERATED_APP_HYDRATION_SIDECAR_PATH",
            "",
        ),
        generation_concurrency=_env_positive_int(
            "CG_RAG_GENERATION_CONCURRENCY",
            "QUESTION_GENERATED_APP_GENERATION_CONCURRENCY",
            DEFAULT_GENERATION_CONCURRENCY,
        ),
        retrieval_concurrency=_env_positive_int(
            "CG_RAG_RETRIEVAL_CONCURRENCY",
            "QUESTION_GENERATED_APP_RETRIEVAL_CONCURRENCY",
            DEFAULT_RETRIEVAL_CONCURRENCY,
        ),
        capacity_wait_timeout_seconds=_env_float(
            "CG_RAG_CAPACITY_WAIT_TIMEOUT_SECONDS",
            "QUESTION_GENERATED_APP_CAPACITY_WAIT_TIMEOUT_SECONDS",
            DEFAULT_CAPACITY_WAIT_TIMEOUT_SECONDS,
        ),
        vision_endpoint=_env_str(
            "CG_RAG_VISION_ENDPOINT",
            "QUESTION_GENERATED_APP_VISION_ENDPOINT",
            "",
        ),
        vision_model=_env_str(
            "CG_RAG_VISION_MODEL",
            "QUESTION_GENERATED_APP_VISION_MODEL",
            "",
        ),
        vision_api_key=_env_str(
            "CG_RAG_VISION_API_KEY",
            "QUESTION_GENERATED_APP_VISION_API_KEY",
            "",
        ),
        vision_enable_thinking=_env_bool(
            "CG_RAG_VISION_ENABLE_THINKING",
            "QUESTION_GENERATED_APP_VISION_ENABLE_THINKING",
            False,
        ),
        vision_streaming=_env_bool(
            "CG_RAG_VISION_STREAMING",
            "QUESTION_GENERATED_APP_VISION_STREAMING",
            True,
        ),
        vision_max_images=_env_positive_int(
            "CG_RAG_VISION_MAX_IMAGES",
            "QUESTION_GENERATED_APP_VISION_MAX_IMAGES",
            DEFAULT_VISION_MAX_IMAGES,
        ),
        vision_max_image_bytes=_env_positive_int(
            "CG_RAG_VISION_MAX_IMAGE_BYTES",
            "QUESTION_GENERATED_APP_VISION_MAX_IMAGE_BYTES",
            DEFAULT_VISION_MAX_IMAGE_BYTES,
        ),
        vision_max_tokens=_env_positive_int(
            "CG_RAG_VISION_MAX_TOKENS",
            "QUESTION_GENERATED_APP_VISION_MAX_TOKENS",
            DEFAULT_VISION_MAX_TOKENS,
        ),
        vision_agentic_max_search_rounds=_env_positive_int(
            "CG_RAG_VISION_AGENTIC_MAX_SEARCH_ROUNDS",
            "QUESTION_GENERATED_APP_VISION_AGENTIC_MAX_SEARCH_ROUNDS",
            DEFAULT_VISION_AGENTIC_MAX_SEARCH_ROUNDS,
        ),
        vision_agentic_retrieval_topk=_env_positive_int(
            "CG_RAG_VISION_AGENTIC_RETRIEVAL_TOPK",
            "QUESTION_GENERATED_APP_VISION_AGENTIC_RETRIEVAL_TOPK",
            DEFAULT_VISION_AGENTIC_RETRIEVAL_TOPK,
        ),
    )