常见问题 (FAQ)

本文档回答了一些使用 Bohrium OpenAPI Python SDK 时的常见问题。

安装和配置

如何安装SDK？

使用 pip 安装：

pip install bohrium-sdk

更多安装选项，请查看安装指南。

如何配置API密钥？

有三种方式：

环境变量（推荐）：
```
export BOHRIUM_ACCESS_KEY="your_key"
```

代码中直接传入：

client = Bohrium(access_key="your_key")

混合使用：参数会覆盖环境变量

更多信息，请查看快速开始。

如何验证安装是否成功？

from bohrium import Bohrium

try:
    client = Bohrium()
    print("安装成功！")
except ImportError as e:
    print(f"安装失败: {e}")

使用问题

同步和异步客户端有什么区别？

同步客户端 (Bohrium): 适用于大多数场景，代码更简单直观
异步客户端 (AsyncBohrium): 适用于需要并发处理的场景，性能更好

选择建议： - 简单脚本或少量请求：使用同步客户端 - 需要处理大量并发请求：使用异步客户端

更多信息，请查看教程中的异步操作部分。

如何处理请求超时？

可以在初始化客户端时设置超时时间：

client = Bohrium(
    access_key="your_key",
    timeout=120.0  # 120秒超时
)

也可以自定义HTTP客户端来设置更细粒度的超时控制。

如何配置重试机制？

client = Bohrium(
    access_key="your_key",
    max_retries=5  # 最多重试5次
)

SDK会自动处理临时性错误并重试。

错误处理

常见的错误类型有哪些？

主要错误类型包括：

AuthenticationError: 认证失败
PermissionDeniedError: 权限不足
NotFoundError: 资源不存在
BadRequestError: 请求参数错误
RateLimitError: 请求频率过高
InternalServerError: 服务器内部错误

如何处理限流错误？

遇到限流时，SDK会自动重试。您也可以手动处理：

from bohrium._exceptions import RateLimitError
import time

try:
    result = client.job.retrieve(job_id="job_id")
except RateLimitError as e:
    wait_time = getattr(e, 'retry_after', 60)
    print(f"遇到限流，等待 {wait_time} 秒")
    time.sleep(wait_time)
    # 重试操作

为什么会出现认证错误？

可能的原因：

API密钥错误或过期
未设置API密钥
密钥格式不正确

检查步骤：

import os

# 检查环境变量
print(f"ACCESS_KEY: {os.environ.get('BOHRIUM_ACCESS_KEY', '未设置')}")

# 或在代码中直接验证
try:
    client = Bohrium(access_key="your_key")
    client.job.list()  # 尝试一个简单操作
except AuthenticationError:
    print("认证失败，请检查密钥")

性能优化

如何提高请求性能？

**使用异步客户端**进行并发请求
复用客户端实例，避免频繁创建
合理设置超时时间，避免过长等待
**使用流式接口**处理大量数据

示例：

# 复用客户端
client = Bohrium(access_key="your_key")

# 并发请求（异步）
import asyncio
from bohrium import AsyncBohrium

async def fetch_multiple():
    client = AsyncBohrium(access_key="your_key")
    results = await asyncio.gather(
        client.job.retrieve("id1"),
        client.job.retrieve("id2"),
        client.job.retrieve("id3"),
    )
    return results

如何处理大量数据的请求？

对于大量数据，建议使用流式接口：

# 流式获取搜索结果
for chunk in client.sigma_search.search_stream(query="query"):
    process_chunk(chunk)

功能问题

支持哪些文件格式的解析？

通用解析器支持多种格式，包括但不限于：

PDF (.pdf)
Word文档 (.doc, .docx)
Excel (.xls, .xlsx)
图片文件 (.jpg, .png, 等)
文本文件 (.txt, .md)

具体支持的格式请参考API文档。

如何获取任务的实时状态？

可以定期轮询任务状态：

import time

while True:
    job = client.job.retrieve(job_id="job_id")
    print(f"状态: {job.status}")

    if job.status in ["completed", "failed"]:
        break

    time.sleep(5)  # 每5秒查询一次

其他问题

SDK是否支持代理？

可以通过自定义HTTP客户端设置代理：

import httpx
from bohrium import Bohrium

proxy_client = httpx.Client(
    proxies="http://proxy.example.com:8080"
)

client = Bohrium(
    access_key="your_key",
    http_client=proxy_client
)

如何在Docker中使用SDK？

在Docker容器中使用时，确保：

通过环境变量传递API密钥
设置适当的网络配置
检查时区和时间设置

FROM python:3.9
RUN pip install bohrium-sdk
ENV BOHRIUM_ACCESS_KEY=your_key
COPY app.py .
CMD ["python", "app.py"]

如何获取帮助？

如果遇到问题：

查看本文档的相应章节
查看 API参考了解API详情
查看示例代码查看示例代码
在GitHub仓库提交Issue

仍然无法解决？

如果以上方法都无法解决您的问题，请：

检查SDK版本是否为最新版本
查看错误信息的详细信息
在GitHub仓库提交Issue，并提供： * 错误信息和堆栈跟踪 * 您的代码示例 * SDK版本和Python版本 * 操作系统信息