> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 何时使用 API

> 用于自定义应用程序的 Python 集成

# 何时使用 Python API

API 为您提供构建自定义应用程序的完整程序化控制。

## 最适合

* **自定义应用程序** - 构建您自己的工具
* **复杂工作流程** - 多步骤管道
* **动态配置** - 即时调整
* **集成** - 与现有代码连接
* **生产系统** - 作为服务部署

## 外观

编写 Python 代码：

```python theme={null}
from aitraining import TextClassification

trainer = TextClassification(
    model="bert-base-uncased",
    learning_rate=2e-5
)

trainer.train(data)
predictions = trainer.predict(texts)
```

## 工作流程示例

```python theme={null}
import pandas as pd
from aitraining import AutoTrainer

# 自定义预处理
data = pd.read_csv("raw_data.csv")
data = clean_and_prepare(data)

# 动态配置
config = {
    "model": get_best_model(data),
    "batch_size": calculate_batch_size(),
    "epochs": 5 if len(data) > 1000 else 10
}

# 使用回调训练
trainer = AutoTrainer(**config)
trainer.train(
    data,
    callbacks=[
        early_stopping,
        checkpoint_best,
        log_to_wandb
    ]
)

# 集成到应用程序
@app.route("/predict")
def predict():
    result = trainer.predict(request.json)
    return jsonify(result)
```

## 优势

* **完全控制** - 访问一切
* **自定义逻辑** - 您的预处理
* **集成** - 与任何 Python 库一起工作
* **动态** - 根据条件调整
* **可测试** - 单元测试您的训练

## 限制

* **更多代码** - 您编写编排
* **复杂性** - 自己处理错误
* **仅 Python** - 不是语言无关的
* **依赖项** - 管理软件包

## 何时切换

当您需要以下功能时使用 CLI：

* 需要简单自动化
* 想要语言无关的解决方案
* 更喜欢配置而不是代码
* 使用非 Python 工具

当您需要以下功能时使用 UI：

* 需要视觉反馈
* 教授他人
* 快速实验
* 数据探索

## 常见用例

### Web 服务

```python theme={null}
from flask import Flask
from aitraining import load_model

app = Flask(__name__)
model = load_model("./trained_model")

@app.route("/api/classify", methods=["POST"])
def classify():
    text = request.json["text"]
    result = model.predict(text)
    return {"label": result}
```

### 数据管道

```python theme={null}
def training_pipeline(df):
    # 自定义清理
    df = remove_outliers(df)
    df = normalize_features(df)

    # 条件训练
    if df.shape[0] > 10000:
        model = "large-model"
    else:
        model = "small-model"

    # 训练
    trainer = AutoTrainer(model=model)
    trainer.train(df)

    return trainer
```

### A/B 测试

```python theme={null}
models = {}

# 训练变体
for config in experiments:
    trainer = create_trainer(config)
    trainer.train(data)
    models[config.name] = trainer

# 比较
results = evaluate_all(models, test_data)
best = select_best(results)
```

### 自定义回调

```python theme={null}
class CustomCallback:
    def on_epoch_end(self, epoch, logs):
        if logs["loss"] < self.threshold:
            send_notification("Training going well!")

        if should_adjust_lr(logs):
            self.trainer.learning_rate *= 0.5

trainer.train(data, callbacks=[CustomCallback()])
```

## API 用户提示

1. **处理异常** - 训练可能失败
2. **添加日志** - 跟踪发生的情况
3. **使用类型提示** - 及早捕获错误
4. **编写测试** - 确保可靠性
5. **记录代码** - 其他人会使用它

## API 独有功能

只有 API 可以做的事情：

* 训练期间的自定义回调
* 动态模型选择
* 复杂数据管道
* 嵌入在应用程序中
* 程序化超参数调整

## 基本模式

```python theme={null}
# 资源的上下文管理器
with AITraining() as trainer:
    trainer.train(data)
    # 自动清理

# 异步训练
async def train_async():
    await trainer.train_async(data)

# 流式预测
for prediction in trainer.predict_stream(texts):
    process(prediction)

# 模型组合
ensemble = Ensemble([
    model1,
    model2,
    model3
])
```

## 集成示例

```python theme={null}
# 与 pandas
df = pd.read_csv("data.csv")
trainer.train(df)

# 与 scikit-learn
from sklearn.model_selection import train_test_split
X_train, X_test = train_test_split(data)

# 与 weights & biases
import wandb
wandb.init(project="my-training")
trainer.train(data, callbacks=[WandbCallback()])

# 与 FastAPI
@app.post("/train")
async def train_endpoint(data: TrainingData):
    result = await trainer.train_async(data)
    return {"model_id": result.id}
```

## 下一步

<CardGroup cols={2}>
  <Card title="API 参考" href="/api/launching-interface">
    完整的 API 文档
  </Card>

  <Card title="CLI 替代方案" href="/foundations/cli-when-to-use">
    何时命令更简单
  </Card>
</CardGroup>