外观

象信控制台
客户端

同步客户端

用 XiangxinClient 提问、列出模型，并配置同步的象信 API 请求。

同步客户端 ​

xiangxin.XiangxinClient ​

python
XiangxinClient(
    *,
    api_key: str | None = None,
    base_url: str | None = None,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx.Timeout | None = None,
    headers: Mapping[str, str] | None = None,
    transport: httpx.BaseTransport | None = None,
    http_client: httpx.Client | None = None,
)

创建一个调用象信 API 的阻塞式 HTTP 客户端，适合脚本、批处理任务以及 Django、Flask 等同步框架。asyncio 程序请改用异步客户端，两者的参数与方法一一对应。

所有参数都只能按关键字传入。显式传入的参数优先于环境变量；值为空或只有空白的环境变量视为未设置。

日志配置

SDK 的日志写入 xiangxin logger，可以按标准 logging 方式配置，也可以设置 XIANGXIN_LOG（debug、info 等）快速开启。鉴权类请求头会被隐去，请求体和响应体不会。详见用法 · 日志。

参数

api_keystr | None默认 None

API 密钥，必需；未传入时读取环境变量 XIANGXIN_API_KEY。首尾空白会被去掉；空密钥、中间含空白、控制字符或非 ASCII 字符的密钥会被拒绝。

base_urlstr | None默认 None

API 根地址；未传入时读取 XIANGXIN_BASE_URL，否则为 https://api.xiangxinai.cn。必须以 http:// 或 https:// 开头，末尾斜杠会被去掉。

modelstr | None默认 None

该客户端的默认模型；未传入时读取 XIANGXIN_DEFAULT_MODEL，否则为 xiangxin-latest。

retryRetryPolicy | None默认 None

控制重试行为的 RetryPolicy；None 使用 RetryPolicy() 的默认值。传 RetryPolicy(max_retries=0) 关闭重试。

timeoutfloat | httpx.Timeout | None默认 None

单次 HTTP 操作的超时，正数（秒）或 httpx.Timeout。传入 http_client 时沿用它的超时设置，否则默认 30 秒。

headersMapping[str, str] | None默认 None

附加到每个请求的请求头。Authorization 和 Accept 由 SDK 设置，不能被覆盖。

transporthttpx.BaseTransport | None默认 None

自定义的 HTTP transport，常用于测试（httpx.MockTransport）。

http_clienthttpx.Client | None默认 None

自己构造好的 httpx.Client（例如配置了代理）；与 transport 互斥。关闭 SDK 客户端时它也会被关闭。

异常

  • XiangxinError：API 密钥缺失或非法、base_url 或 timeout 非法。
  • ValueError：同时传入了 transport 和 http_client。

示例

python
from xiangxin import Choice, Noul, XiangxinClient

with XiangxinClient() as client:
    result = client.system_one(
        state="我被重复扣费了两次，请帮忙处理。",
        questions={
            "billing": Noul(instructions="这是否与扣费有关？"),
            "tone": Choice(
                instructions="语气是？",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

models ​

属性

python
models: Models

Models 资源的入口。

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

system_one ​

python
system_one(
    state: JSONContent,
    questions: Mapping[str, Question],
    *,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
    extra_body: Mapping[str, Any] | None = None,
    response_model: type[Any] | None = None,
) -> Any
python
system_one(
    state: JSONContent,
    questions: Mapping[str, Question],
    *,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
    extra_body: Mapping[str, Any] | None = None,
    response_model: None = None,
) -> SystemOneResponse
python
system_one(
    state: JSONContent,
    questions: Mapping[str, Question],
    *,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
    extra_body: Mapping[str, Any] | None = None,
    response_model: type[ResponseT],
) -> ResponseT

对文本或结构化的 state 提出一组命名问题，调用 POST /v1/systemone，一次返回全部答案。原理见系统一。

参数

stateJSONContent必填

要评估的文本、JSON 对象或数组，不能为 None。见状态。

questionsMapping[str, Question]必填

非空映射：问题名 → 问题对象或问题字典。

modelstr | None默认 None

仅本次调用使用的模型；None 沿用客户端默认值。

retryRetryPolicy | None默认 None

仅本次调用使用的重试策略，覆盖客户端级设置。

timeoutfloat | httpx.Timeout | None默认 None

仅本次调用使用的单次 HTTP 操作超时（秒），覆盖客户端级设置。

extra_headersMapping[str, str] | None默认 None

仅本次调用附加的请求头；Authorization 与 Accept 仍受保护。

extra_bodyMapping[str, Any] | None默认 None

额外的请求体顶层字段，在 state、model、questions 设置之后浅合并进去。后写者生效：与这三个键同名时会覆盖它们。用法见前向兼容。

response_modeltype[ResponseT] | None默认 None

描述响应 JSON 的 pydantic BaseModel 类型（包括其中嵌套的答案模型）。见带类型的响应。

返回

  • SystemOneResponse：未传 response_model 时返回，包含按问题名索引的答案、实际模型与 token 用量。
  • ResponseT：传入 response_model 时返回该模型的实例。

异常

  • XiangxinError：请求发出前的本地校验失败，例如 state 为 None、questions 为空、问题字典缺少 type、Choice / Score 字典的 criteria 为空。
  • APIError：重试后服务端仍返回不成功的 HTTP 响应。
  • APIConnectionError：重试后仍无法连接或超时。
  • APIResponseValidationError：响应体与响应模型不符。

示例

用问题类构造问题：

python
with XiangxinClient() as client:
    result = client.system_one(
        state="我被重复扣费了两次，请帮忙处理。",
        questions={
            "billing": Noul(instructions="这是否与扣费有关？"),
            "tone": Choice(
                instructions="语气是？",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

以字典形式传入问题：

python
with XiangxinClient() as client:
    result = client.system_one(
        state={"message": "我被重复扣费了两次，请帮忙处理。"},
        questions={
            "billing": {"type": "noul", "instructions": "这是否与扣费有关？"},
            "tone": {
                "type": "choice",
                "instructions": "语气是？",
                "criteria": {"calm": None, "angry": None},
            },
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

with_raw_response ​

属性

system_one 与 models.list 的“原始响应”版本：参数完全相同，但返回 RawResponse，让你在解析之前拿到状态码和全部响应头。

python
raw = client.with_raw_response.system_one(state, questions)

print(raw.status_code, raw.request_id)
print(raw.headers["x-xiangxin-model-ms"])
resp = raw.parse()  # SystemOneResponse，结果会缓存

models = client.with_raw_response.models.list().parse()

大多数情况下不需要它：普通响应对象上已有 request_id、model_ms、total_ms 和 raw_http_response。

base_url / model / retry ​

属性

python
base_url: str
model: str
retry: RetryPolicy

解析后的 API 根地址、默认模型和客户端级重试策略（即环境变量与默认值生效之后的结果）。

close ​

python
close() -> None

释放网络资源，关闭底层 HTTP 客户端（包括你传入的 http_client）。用 with XiangxinClient() as client: 时会自动调用。

XiangxinClient 底层是 httpx.Client，可以在多个线程间共享。建议在进程启动时创建一个客户端全程复用，而不是每个请求新建一个。

Models 资源 ​

通过 XiangxinClient.models 访问。

xiangxin.Models ​

访问当前账号可用的模型，通过 XiangxinClient.models 获得。

list ​

python
list(
    *,
    retry: RetryPolicy | None = None,
    timeout: float | httpx.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
) -> ListModelsResponse

调用 GET /v1/models，列出当前账号可以填进 model 的名称。

参数

retryRetryPolicy | None默认 None

仅本次调用使用的重试策略，覆盖客户端级设置。

timeoutfloat | httpx.Timeout | None默认 None

仅本次调用使用的超时；None 沿用客户端设置。

extra_headersMapping[str, str] | None默认 None

附加请求头；Authorization 与 Accept 仍受保护。

返回

  • ListModelsResponse：其 models 字段列出每个模型的名称、说明和发布日期。

异常

示例

python
from xiangxin import XiangxinClient

with XiangxinClient() as client:
    models = client.models.list()
    for m in models.models:
        print(m.name, m.release_date)