# 模型

让 Mini App 使用 Cowork 里已经设置好的 AI 模型。API 密钥留在 Cowork 内部，不会到达页面。每次调用是一次请求、一次回复：没有工具，也没有对话历史。

## MAESTROSDK.llm.providers() <Badge type="warning" text="尚未发布" />

列出可以使用的模型提供方（已登录或已填密钥），以及它们的模型和思考强度。

### 参数

无。

### 返回值

`Promise<Provider[]>`。没有设置任何提供方、页面没有 Cowork 标签页身份或调用失败时，返回空列表。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 提供方 id，作为 `provider` 传给 `complete` |
| `label` | `string` | 显示的名称 |
| `models[].id` | `string` | 模型 id，作为 `model` 传入 |
| `models[].label` | `string` | 显示的名称 |
| `models[].defaultEffort` | `string` | Cowork 默认使用的思考强度 |
| `models[].efforts[]` | `{ id, label }[]` | 这个模型接受的思考强度；把其中一个 `id` 作为 `effort` 传入 |

### 示例

```js
const providers = await MAESTROSDK.llm.providers();
const first = providers[0]?.models[0];
```

## MAESTROSDK.llm.complete(request) <Badge type="warning" text="尚未发布" />

把一个提示词发给一个模型，返回它的文字回复。

### 参数

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `request.provider` | `string` | 是 | `providers()` 返回的某个提供方 `id` |
| `request.model` | `string` | 是 | 该提供方的某个模型 `id` |
| `request.effort` | `string` | 是 | 该模型的某个思考强度 `id` |
| `request.prompt` | `string` | 是 | 提示词，最多 32,000 个字符 |

一次调用最多等待模型 120 秒。

### 返回值

`Promise<{ ok: true, text: string } | { ok: false, error: string }>`

### 错误

| `error` | 含义 |
|---|---|
| `provider, model, effort and prompt are required` | 缺少某个字段或字段为空 |
| `prompt_too_long` | 提示词超过 32,000 个字符 |
| `empty_prompt` | 提示词只有空格 |
| `unknown_model` | 这个组合不在 `providers()` 里 |
| `empty_reply` | 模型没有返回文字 |
| `no_instance` | 页面没有 Cowork 标签页身份 |
| `host_unavailable` | Cowork 无法接受这次调用 |
| 其他任何文字 | 模型自己的错误信息，或 `model_failed` |

### 示例

```js
const [provider] = await MAESTROSDK.llm.providers();
const model = provider.models[0];
const reply = await MAESTROSDK.llm.complete({
  provider: provider.id,
  model: model.id,
  effort: model.defaultEffort,
  prompt: 'Summarise this note in one sentence: ...'
});
if (reply.ok) show(reply.text); else showError(reply.error);
```

## 相关

- [AI 对话：模型与思考强度](https://docs.micromeet.ai/zh/chat/models.md): 在哪里设置模型
- [概览](https://docs.micromeet.ai/zh/miniapp-sdk/overview.md): Mini App SDK 的所有模块