象信 Python SDK

源码托管在 GitHub：xiangxinai/xiangxin-sdk-python。

xiangxin-sdk 为象信 API 提供异步与同步两种 Python 客户端：问题用 Noul、Choice、Score 三个类来写，答案以带类型的 pydantic 模型返回，出错时抛出按 HTTP 状态码细分的异常，遇到限流和过载会自动退避重试。需要 Python 3.10 及以上。还不了解象信一号？先从介绍读起。

快速开始

1. 安装 SDK：

   uv

   uv add xiangxin-sdk

   pip

   pip install xiangxin-sdk

   包在 PyPI 上叫 xiangxin-sdk，导入时叫 xiangxin。

2. 在环境变量中设置 XIANGXIN_API_KEY（在控制台创建密钥）：

   export XIANGXIN_API_KEY="sk-xx-你的密钥"

3. 调用 System One API。异步写法使用 AsyncXiangxinClient，同步写法使用 XiangxinClient：

   异步

   import asyncio
   
   from xiangxin import AsyncXiangxinClient, Choice, Noul, Score
   
   
   async def main() -> None:
       async with AsyncXiangxinClient() as client:
           response = await client.system_one(
               state={"document": "我被重复扣费了两次，请尽快处理！"},
               questions={
                   "billing": Noul(instructions="这张工单是否与扣费有关？"),
                   "tone": Choice(
                       instructions="客户的语气是？",
                       criteria={"calm": None, "frustrated": None, "angry": None},
                   ),
                   "urgency": Score(
                       instructions="这张工单有多紧急？",
                       criteria=["可以等", "本周内处理", "今天必须处理"],
                   ),
               },
           )
   
       print(response.nouls["billing"].noul)
       print(response.choices["tone"].choice)
       print(response.scores["urgency"].score)
   
   
   asyncio.run(main())

   同步

   from xiangxin import Choice, Noul, Score, XiangxinClient
   
   with XiangxinClient() as client:
       response = client.system_one(
           state={"document": "我被重复扣费了两次，请尽快处理！"},
           questions={
               "billing": Noul(instructions="这张工单是否与扣费有关？"),
               "tone": Choice(
                   instructions="客户的语气是？",
                   criteria={"calm": None, "frustrated": None, "angry": None},
               ),
               "urgency": Score(
                   instructions="这张工单有多紧急？",
                   criteria=["可以等", "本周内处理", "今天必须处理"],
               ),
           },
       )
   
   print(response.nouls["billing"].noul)
   print(response.choices["tone"].choice)
   print(response.scores["urgency"].score)

注意

不要把密钥写进代码仓库或前端代码。API 密钥属于组织，拿到它的人都能以你的组织身份调用并产生费用。

用法

更多写法见用法；所有类、参数与异常见 API 参考。用 Node.js / TypeScript？请看 JavaScript SDK。