模型加载与配置

用于实例化提供商配置定义的聊天模型的辅助工具。

load_models_config `cached`

load_models_config(config_path=None)

加载并缓存提供商配置文件。

参数：

名称	类型	描述	默认
`config_path`	`str \| Path \| None`	配置文件的可选路径覆盖。	`None`

返回：

类型	描述
`dict[str, Any]`	dict[str, Any]: 解析后的提供商配置数据。

引发：

类型	描述
`FileNotFoundError`	如果无法找到配置文件。
`JSONDecodeError`	如果文件包含无效的 JSON。

示例：

>>> config = load_models_config()
>>> isinstance(config, dict)
True
>>> "openai" in config
True

>>> config = load_models_config("custom_models.json")
>>> # 从自定义路径加载配置

list_models

list_models(provider, category=None, *, config_path=None)

返回给定提供商/类别的已配置模型。

参数：

名称	类型	描述	默认
`provider`	`str`	配置文件中定义的提供商键。	必需
`category`	`str \| None`	可选的类别键，例如 `omni_models`。	`None`
`config_path`	`str \| Path \| None`	配置文件路径的覆盖。	`None`

返回：

类型	描述
`list[dict[str, Any]]`	list[dict[str, Any]]: 包含元数据的匹配模型条目。

示例：

>>> models = list_models("openai")
>>> isinstance(models, list)
True
>>> len(models) > 0
True

>>> chat_models = list_models("openai", "chat_models")
>>> # 获取 OpenAI 的聊天模型列表

resolve_model_credentials

resolve_model_credentials(
    model_name,
    *,
    provider=None,
    config_path=None,
    api_key=None,
    dashscope_region=None,
)

解析模型可用的全部提供商、基础 URL 和 API 密钥组合。

参数：

名称	类型	描述	默认
`model_name`	`str`	要检查的模型标识符。	必需
`provider`	`str \| None`	显式指定的提供商名称。	`None`
`config_path`	`str \| Path \| None`	可选的配置文件覆盖。	`None`
`api_key`	`str \| None`	优先使用的显式 API 密钥。	`None`
`dashscope_region`	`str \| None`	DashScope 基础 URL 的区域选择器。	`None`

返回：

类型	描述
`list[tuple[str, str \| None, str \| None]]`	list[tuple[str, str \| None, str \| None]]: (provider, base_url, api_key)
`list[tuple[str, str \| None, str \| None]]`	组合，覆盖所有匹配的提供商和 URL。

示例：

>>> resolve_model_credentials("gpt-4")
[('openai', None, 'sk-...')]

>>> resolve_model_credentials("qwen-turbo", dashscope_region="beijing")
[('dashscope', 'https://dashscope.aliyuncs.com/compatible-mode/v1', 'ak-...')]

>>> resolve_model_credentials("openai/gpt-4o", provider="openrouter")
[('openrouter', 'https://openrouter.ai/api/v1', 'sk-...')]

create_chat_model

create_chat_model(
    model_name,
    *,
    temperature=0.0,
    provider=None,
    config_path=None,
    api_key=None,
    dashscope_region=None,
    client_kwargs=None,
)

根据提供商配置实例化聊天模型。

参数：

名称	类型	描述	默认
`model_name`	`str`	要实例化的模型名称。	必需
`temperature`	`float`	传递给底层客户端的温度值。	`0.0`
`provider`	`str \| None`	显式指定的提供商名称。	`None`
`config_path`	`str \| Path \| None`	可选的配置路径覆盖。	`None`
`api_key`	`str \| None`	显式传入的 API 密钥。	`None`
`dashscope_region`	`str \| None`	DashScope 基础 URL 的区域选择器。	`None`
`client_kwargs`	`Mapping[str, Any] \| None`	额外传递的客户端参数。	`None`

返回：

名称	类型	描述
`BaseLanguageModel`	`BaseLanguageModel`	可直接调用的 LLM 客户端实例。

引发：

类型	描述
`ModelConfigError`	当无法解析 API 密钥或配置缺失时抛出。
`FileNotFoundError`	当配置路径不存在时抛出。

build_public_models_catalog

build_public_models_catalog(*, config_path=None)

构建用于 API 输出的公开模型清单。

参数：

名称	类型	描述	默认
`config_path`	`str \| Path \| None`	模型配置文件的可选路径覆盖。	`None`

返回：

类型	描述
`dict[str, Any]`	dict[str, Any]: 公开模型清单，包含提供商与模型列表。

Bases: BaseSettings

应用主配置 - 聚合所有子配置。

属性：

名称	类型	描述
`app_name`	`str`	应用名称。
`log_level`	`str`	日志级别。
`postgres_user`	`str`	PostgreSQL 用户名。
`postgres_password`	`SecretStr`	PostgreSQL 密码。
`database_url`	`str`	完整数据库 URL 覆盖。
`minio_access_key`	`str`	MinIO 访问密钥。
`minio_secret_key`	`SecretStr`	MinIO 密钥。
`minio_root_user`	`str`	Docker MinIO root 用户。
`minio_root_password`	`SecretStr`	Docker MinIO root 密码。
`database`	`DatabaseSettings`	数据库子配置。
`chat_model`	`ChatModelSettings`	聊天模型子配置。
`minio`	`MinioSettings`	MinIO 子配置。
`qdrant`	`QdrantSettings`	Qdrant 子配置。
`embedding`	`EmbeddingSettings`	Embedding 子配置。
`rerank`	`RerankSettings`	Rerank 子配置。
`chunking`	`ChunkingSettings`	分块子配置。
`timeouts`	`TimeoutSettings`	超时子配置。
`mcp`	`MCPSettings`	MCP 出站能力配置。
`agent_types`	`AgentTypesSettings`	智能体类型配置。
`base_dir`	`Path`	项目根目录。
`log_dir`	`Path`	日志目录。
`log_file`	`Path`	日志文件路径。

resolved_database_url `property`

resolved_database_url

解析最终 DATABASE_URL：env var > TOML + credentials > default。

返回：

名称	类型	描述
`str`	`str`	最终的数据库连接 URL。

resolved_minio_access_key `property`

resolved_minio_access_key

MinIO access key: MINIO_ACCESS_KEY > MINIO_ROOT_USER > default。

返回：

名称	类型	描述
`str`	`str`	解析后的 MinIO access key。

resolved_minio_secret_key `property`

resolved_minio_secret_key

MinIO secret key: MINIO_SECRET_KEY > MINIO_ROOT_PASSWORD > default。

返回：

名称	类型	描述
`str`	`str`	解析后的 MinIO secret key。

ensure_log_directory

ensure_log_directory()

确保日志目录存在。

引发：

类型	描述
`OSError`	当无法创建目录时抛出。

settings_customise_sources `classmethod`

settings_customise_sources(settings_cls, **kwargs)

配置源优先级：env vars > .env > TOML [app] > defaults。

嵌套子模型各自读取 config.toml 对应 section。

参数：

名称	类型	描述	默认
`settings_cls`	`type[BaseSettings]`	Settings 类。	必需
`**kwargs`	`Any`	默认源参数。	`{}`

返回：

类型	描述
`tuple[Any, ...]`	tuple[Any, ...]: 配置源元组，按优先级排列。

模型加载与配置

load_models_config cached