TS TypeSafe 文档中文版
原文 ↗

同步客户端

使用 TypeSafeClient 提问、列出模型，并配置同步的 TypeSafe API 请求。

typesafe_sdk.TypeSafeClient

为 TypeSafe AI API 创建一个 HTTP 客户端。

显式选项优先于环境变量；为空或只含空白字符的环境变量值会被忽略。

提示

日志配置

SDK 记录日志到 typesafe_sdk logger；可通过标准 logging 来配置它，或设置 TYPESAFE_LOG_LEVEL（debug、info 等）以快速获得默认行为。日志输出中会隐去敏感的请求头；请求体和响应体则不会隐去。

参数：

  • api_key (str | None, default: None ) –

    必需的 API key；可通过 TYPESAFE_API_KEY 环境变量设置。首尾空白会被去除。空 key、内部空白、控制字符以及非 ASCII 字符都会被拒绝。

  • model (str | None, default: None ) –

    模型名称；可通过 TYPESAFE_DEFAULT_MODEL 环境变量设置。

  • retry (RetryPolicy | None, default: None ) –

    控制重试行为的 RetryPolicy；可用选项及其默认值参见 RetryPolicy。传入 RetryPolicy(max_retries=0) 可禁用重试。

  • timeout (float | httpx2.Timeout | None, default: None ) –

    HTTP 操作的超时时间。若提供了 http_client，则继承其 http_client.timeout，否则使用 SDK 默认值。

  • headers (Mapping[str, str] | None, default: None ) –

    要设置的附加请求头。

  • transport (httpx2.BaseTransport | None, default: None ) –

    可选的定制 HTTP transport，在本 SDK 客户端关闭时会被关闭。

  • http_client (httpx2.Client | None, default: None ) –

    可选的 httpx2.Client；与 transport 互斥。在本 SDK 客户端关闭时会被关闭。

  • base_url (str | None, default: None ) –

    API 根地址；可通过 TYPESAFE_BASE_URL 环境变量设置。

抛出：

  • TypeSafeError –

    API key 缺失或无效，或者超时时间无效。

  • ValueError –

    同时提供了 transport 和 http_client。

示例：

python
from typesafe_sdk import Choice, Noul, TypeSafeClient
 
with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(instructions="Is this about billing?"),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

models

cached property

Models API 资源的访问器。

示例：

python
with TypeSafeClient() as client:
    models = client.models.list()

system_one

回答关于文本或结构化状态的具名问题。

详情参见 System One。

参数：

  • state (JSONContent) –

    要评估的文本、JSON 对象或数组。详情参见 state。

  • questions (Mapping[str, Question]) –

    从名称到问题对象或原始字典的非空映射。

  • model (str | None, default: None ) –

    模型覆盖值；None 表示继承客户端默认值。

  • retry (RetryPolicy | None, default: None ) –

    可选的重试策略，仅对本次调用覆盖客户端级别的取值。

  • timeout (float | httpx2.Timeout | None, default: None ) –

    可选的 http 操作超时时间（秒），仅对本次调用覆盖客户端级别的取值。

  • extra_headers (Mapping[str, str] | None, default: None ) –

    要设置的附加请求头。

  • extra_body (Mapping[str, JSONValue | None] | None, default: None ) –

    附加的顶层请求体字段，在设置完 state、model 和 questions 之后浅合并到请求体之上。合并采用后写覆盖：与 state、model 或 questions 冲突的键会覆盖它们，且对象值会被整体替换，而不是深度合并。

  • response_model (type[ResponseT] | None, default: None ) –

    可选的 Pydantic BaseModel 类型，用于描述 JSON 响应体，包括其中任何嵌套的答案模型。

返回：

  • SystemOneResponse | ResponseT –

    response_model 的实例，或者以问题名称为键存放答案的 SystemOneResponse

  • SystemOneResponse | ResponseT –

    以及模型和 token 用量详情（在未提供自定义模型时）。

抛出：

示例：

用命名参数创建问题：

python
with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(instructions="Is this about billing?"),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

以字典形式传入问题：

python
with TypeSafeClient() as client:
    result = client.system_one(
        state={"message": "I was charged twice. Please help."},
        questions={
            "billing": {"type": "noul", "instructions": "Is this about billing?"},
            "tone": {
                "type": "choice",
                "instructions": "What is the tone?",
                "criteria": {"calm": None, "angry": None},
            },
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

close

python
close() -> None

释放网络资源并关闭底层的 HTTP 客户端，包括外部传入的那个。

Models 资源

通过 TypeSafeClient.models 访问。

typesafe_sdk.Models

访问该账户可用的模型，通过 TypeSafeClient.models 访问。

list

列出该账户可用的模型。

参数：

  • retry (RetryPolicy | None, default: None ) –

    可选的重试策略，仅对本次调用覆盖客户端级别的取值。

  • timeout (float | httpx2.Timeout | None, default: None ) –

    按操作覆盖的超时时间；None 表示继承客户端设置。

  • extra_headers (Mapping[str, str] | None, default: None ) –

    附加请求头的覆盖项；认证、SDK 标识以及 Accept 仍受保护。

返回：

抛出：

示例：

python
from typesafe_sdk import TypeSafeClient
 
with TypeSafeClient() as client:
    models = client.models.list()