配置

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 / QUESTION_APP_CONFIG_DIR 将 YAML 配置写入这些环境变量（仅写入当前进程中尚未存在的键）。YAML 各字段定义详见 字段手册。

retrieve cache 的容量与 TTL 仍由配置控制，但缓存 key 会额外引入当前 profile fingerprint。fingerprint 基于运行时 profile、语料/索引摘要以及 embedding/rerank 配置生成，无需单独配置。

cg_rag_config

CgRagConfig dataclass

Source code in 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_pixels: int = DEFAULT_VISION_MAX_PIXELS
    vision_max_dimension: int = DEFAULT_VISION_MAX_DIMENSION
    vision_normalized_max_dimension: int = DEFAULT_VISION_NORMALIZED_MAX_DIMENSION
    vision_jpeg_quality: int = DEFAULT_VISION_JPEG_QUALITY
    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
    # controller = observe→server retrieve→synthesize. Restore native ReAct with
    # CG_RAG_VISION_AGENTIC_WORKFLOW=continuous.
    vision_agentic_workflow: str = DEFAULT_VISION_AGENTIC_WORKFLOW
    # Shared inbound Bearer for HTTP + MCP. Empty = auth disabled (loopback-only OK).
    inbound_token: str = ""
    # OpenAPI /docs. Default false; keep closed when token is set or bind is non-loopback.
    expose_docs: bool = False

    # Named behaviour pack (e10/continuous_base/controller/controller_wip).
    # Empty => derive from vision_agentic_workflow (continuous -> e10).
    vision_profile: str = ""
    # Whole-turn wall budget (seconds). 0/empty => use profile default.
    vision_total_budget_seconds: float = 0.0
    # SSE keepalive interval during long VLM/retrieval stages; 0 disables.
    vision_sse_heartbeat_seconds: float = -1.0
    # Tri-state string: "" = profile default, true/false override.
    vision_strict_retrieval_failure: str = ""
    vision_upstream_retry_count: int = 0
    vision_upstream_retry_sleep_seconds: float = -1.0
    # Text model for /vision/hybrid. Deliberately not the constrained-generation
    # model: production uses deepseek-chat there and deepseek-flash here.
    hybrid_generation_endpoint: str = ""
    hybrid_generation_model: str = ""
    hybrid_generation_api_key: str = ""

    @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 hybrid_generation_configured(self) -> bool:
        return bool(
            self.hybrid_generation_endpoint
            and self.hybrid_generation_model
            and self.hybrid_generation_api_key
        )

    @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_pixels=_env_positive_int(
            "CG_RAG_VISION_MAX_PIXELS",
            "QUESTION_GENERATED_APP_VISION_MAX_PIXELS",
            DEFAULT_VISION_MAX_PIXELS,
        ),
        vision_max_dimension=_env_positive_int(
            "CG_RAG_VISION_MAX_DIMENSION",
            "QUESTION_GENERATED_APP_VISION_MAX_DIMENSION",
            DEFAULT_VISION_MAX_DIMENSION,
        ),
        vision_normalized_max_dimension=_env_positive_int(
            "CG_RAG_VISION_NORMALIZED_MAX_DIMENSION",
            "QUESTION_GENERATED_APP_VISION_NORMALIZED_MAX_DIMENSION",
            DEFAULT_VISION_NORMALIZED_MAX_DIMENSION,
        ),
        vision_jpeg_quality=_env_positive_int(
            "CG_RAG_VISION_JPEG_QUALITY",
            "QUESTION_GENERATED_APP_VISION_JPEG_QUALITY",
            DEFAULT_VISION_JPEG_QUALITY,
        ),
        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,
        ),
        vision_agentic_workflow=_env_agentic_workflow(),
        inbound_token=_env_str("CG_RAG_INBOUND_TOKEN", "", ""),
        expose_docs=_env_bool("CG_RAG_EXPOSE_DOCS", "", False),
        vision_profile=_env_vision_profile(),
        vision_total_budget_seconds=_env_non_negative_float(
            "CG_RAG_VISION_TOTAL_BUDGET_SECONDS",
            "QUESTION_GENERATED_APP_VISION_TOTAL_BUDGET_SECONDS",
            0.0,
        ),
        vision_sse_heartbeat_seconds=_env_float(
            "CG_RAG_VISION_SSE_HEARTBEAT_SECONDS",
            "QUESTION_GENERATED_APP_VISION_SSE_HEARTBEAT_SECONDS",
            -1.0,
        ),
        vision_strict_retrieval_failure=_env_str(
            "CG_RAG_VISION_STRICT_RETRIEVAL_FAILURE",
            "QUESTION_GENERATED_APP_VISION_STRICT_RETRIEVAL_FAILURE",
            "",
        ),
        vision_upstream_retry_count=_env_non_negative_int(
            "CG_RAG_VISION_UPSTREAM_RETRY_COUNT",
            "QUESTION_GENERATED_APP_VISION_UPSTREAM_RETRY_COUNT",
            0,
        ),
        vision_upstream_retry_sleep_seconds=_env_float(
            "CG_RAG_VISION_UPSTREAM_RETRY_SLEEP_SECONDS",
            "QUESTION_GENERATED_APP_VISION_UPSTREAM_RETRY_SLEEP_SECONDS",
            -1.0,
        ),
        hybrid_generation_endpoint=_env_str("CG_RAG_HYBRID_GENERATION_ENDPOINT", "", ""),
        hybrid_generation_model=_env_str("CG_RAG_HYBRID_GENERATION_MODEL", "", ""),
        hybrid_generation_api_key=_env_str("CG_RAG_HYBRID_GENERATION_API_KEY", "", ""),
    )