# opensearch-model

Part of **OPENSEARCH**

# OpenSearch Model Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Get Model Details | Synchronous | Retrieve detailed information about deployed models. |
| Get Model Report | Synchronous | Generate and retrieve reports about model performance. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication as the primary method.

- Include the header: `Authorization: Bearer <your-access-token>`
- Store your access token in the environment variable: `DASHSCOPE_API_KEY`
- While other methods may exist, Bearer Token is the standard for OpenSearch Model Management APIs.

### Service Endpoint
The base URL is region-specific:

- China regions: `https://opensearch.{region}.aliyuncs.com`
- International regions: `https://opensearch.{region}.aliyuncs.com`

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-shanghai`

### Synchronous Pattern
Both supported functions use a **Synchronous** calling pattern:

1. Send an HTTP GET request to the appropriate endpoint with required path parameters.
2. Include the `Authorization: Bearer <token>` header.
3. Receive a complete JSON response immediately (no polling or streaming).
4. Parse the response body for model details or report data.

No asynchronous or streaming patterns are used in this domain.

## Parameter Reference

### Get Model Report

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| appGroupIdentity | string | Yes | — | — | The name of the application. |
| modelName | string | Yes | — | — | The name of the model. |

## Code Examples

### Get Model Report - Bash - All Regions

```bash
curl -X GET 'https://opensearch.cn-hangzhou.aliyuncs.com/v4/openapi/app-groups/my_app/algorithm/models/model_name/report' \
-H 'Authorization: Bearer <your-access-token>'
```

### Get Model Details - Bash - China Region

```bash
curl -X GET 'https://opensearch.cn-hangzhou.aliyuncs.com/v4/openapi/app-groups/my_app/algorithm/models/model_name' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

### Get Model Report - Python - International Region

```python
import requests
import os

token = os.getenv("DASHSCOPE_API_KEY")
url = "https://opensearch.cn-shanghai.aliyuncs.com/v4/openapi/app-groups/my_app/algorithm/models/my_model/report"
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(url, headers=headers)
print(response.json())
```

### Get Model Details - Python - China Region

```python
import requests
import os

token = os.getenv("DASHSCOPE_API_KEY")
url = "https://opensearch.cn-hangzhou.aliyuncs.com/v4/openapi/app-groups/appGroupName/algorithm/models/pop_1212"
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(url, headers=headers)
data = response.json()
print(f"Model: {data['name']}, Status: {data['status']}, AUC: {data['auc']}")
```

## Response Format

```json
{
    "id": 113023,
    "groupId": "100297752",
    "groupName": "appGroupName",
    "type": "pop",
    "name": "pop_1212",
    "trainTarget": "ctr",
    "cron": "15 0 */2 * *",
    "cronEnabled": true,
    "behaviorEnabled": true,
    "behaviorFromGroupName": "DemoModelName",
    "lastTrainingTime": 1543233439000,
    "auc": 0.85,
    "status": "train_success",
    "progress": 69,
    "isAlreadyDeployed": true,
    "industry": "general",
    "filter": "user_id=1,level=1",
    "fields": [
        {
            "name": "item_title",
            "appFieldType": "title"
        },
        {
            "name": "item_content"
        },
        {
            "name": "item_title_keep",
            "processType": "reserve"
        }
    ],
    "extend": {
        "useHotQuery": true,
        "useHistoryQuery": true
    }
}
```

**Key Fields**:
- `id` — Unique model identifier
- `name` — Model name
- `type` — Model type (e.g., "pop")
- `status` — Current training/deployment status (e.g., "train_success")
- `progress` — Training progress percentage
- `auc` — Model performance metric (Area Under Curve)
- `lastTrainingTime` — Timestamp of last training completion
- `fields[].name` — Name of input field
- `fields[].appFieldType` — Semantic type of field (e.g., "title")
- `fields[].processType` — Processing instruction (e.g., "reserve")
- `extend.useHotQuery` — Whether hot query features are enabled
- `extend.useHistoryQuery` — Whether historical query data is used

For Get Model Report, the response is:

```json
{
    "result": "{}",
    "requestId": "ABCDEFGH"
}
```

**Key Fields**:
- `result` — JSON-encoded model report data (may be empty `{}`)
- `requestId` — Unique ID for the API request (useful for support)

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Bad Request: The request parameters are invalid or missing. | Verify `appGroupIdentity` and `modelName` are correct and non-empty. |
| 401 | Unauthorized: Authentication failed or access token is invalid. | Check that your Bearer token is valid and properly formatted. |
| 403 | Forbidden: The user does not have permission to access this resource. | Ensure your account has read permissions on the OpenSearch application. |
| 404 | Not Found: The specified application group or model does not exist. | Confirm the application and model names exist in the target region. |
| 500 | Internal Server Error: An unexpected error occurred on the server side. | Retry the request; if persistent, contact Alibaba Cloud support with the `requestId`. |

## Pricing & Billing

### Billing Model
Billing is **per request** for both model details and model report operations.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| standard | 0.0001 / | 0.0002 / |
| default | 0.0001 / | 0.0001 / |

### Free Tier
Monthly free quota of **1000 requests** for both operations. Resets every month.

### Usage Limits
- Model report API: **100 QPS per account**
- Model details: **Single request max 8192 characters**

### Billing Notes
Model management operations (details, report) are billed per request; model deployment and training incur separate charges.

## FAQ

Q: How do I authenticate my OpenSearch Model Management API calls?
A: Use a Bearer Token in the `Authorization` header: `Authorization: Bearer <your-access-token>`. Store your token in the `DASHSCOPE_API_KEY` environment variable for security.

Q: Are these APIs asynchronous or synchronous?
A: Both Get Model Details and Get Model Report are **synchronous**—they return the full response immediately upon request.

Q: What regions support the Model Management API?
A: Supported in all Alibaba Cloud OpenSearch regions, including `cn-hangzhou`, `cn-shanghai` (China), and `cn-shanghai` (international). Use the region-specific endpoint.

Q: Why am I getting a 404 error when fetching model details?
A: Verify that both the application group name (`appGroupIdentity`) and model name (`modelName`) are spelled correctly and exist in the specified region.

Q: Is there a free tier for model inspection APIs?
A: Yes—both APIs include **1000 free requests per month**. Usage beyond that is billed per request.