Arquivo

API de gerenciamento de arquivos

Carregue arquivos para análise de documentos ou processamento em lote usando a API Files compatível com OpenAI.

Uso

Use o OpenAI SDK (Python/Node.js) ou HTTP para fazer upload, consultar, listar e excluir arquivos.

Pré-requisitos:

• Uma chave de API: Crie uma chave de API e Exportar a chave de API como variável de ambiente.

• Para usar o OpenAI SDK, instale o OpenAI SDK.

Disponibilidade do modelo

IDs de arquivo funcionam com:

• Processamento em lote: upload de arquivo em lote.
• Ajuste fino: upload do arquivo de dados de treinamento.

Pontos finais

Primeiros passos

Carregar um arquivo

Você pode armazenar até 10.000 arquivos e 100 GB no total. Os arquivos nunca expiram.

Para análise de documentos

Definir purpose para file-extract. Formatos suportados: arquivos de texto (TXT, DOCX, PDF, XLSX, EPUB, MOBI, MD, CSV, JSON) e imagens (BMP, PNG, JPG/JPEG, GIF, PDFs digitalizados). Tamanho máximo do arquivo: 150 MB.

Solicitar exemplos

Python

```python
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)

# test.txt is a local sample file.
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())
```

Node.js

```javascript
import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});

const fileObject = await client.files.create({
  file: fs.createReadStream("test.txt"),
  purpose: "file-extract",
});
console.log(fileObject);
```

cURL

```bash
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/files \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F 'file=@"test.txt"' \
  -F 'purpose="file-extract"'
```

Exemplo de resposta

{
  "id": "file-fe-xxx",
  "bytes": 2055,
  "created_at": 1729065448,
  "filename": "test.txt",
  "object": "file",
  "purpose": "file-extract",
  "status": "processed",
  "status_details": null
}

Para processamento em lote

Definir purpose para batch. Faça upload de um arquivo JSONL em conformidade com Requisitos de arquivo em lote. Tamanho máximo do arquivo: 500 MB.

Para chamadas em lote, consulte API em lote.

Solicitar exemplos

Python

```python
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)

# test.jsonl is a local sample file.
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())
```

Node.js

```javascript
import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});

const fileObject = await client.files.create({
  file: fs.createReadStream("test.jsonl"),
  purpose: "batch",
});
console.log(fileObject);
```

cURL

```bash
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/files \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F 'file=@"test.jsonl"' \
  -F 'purpose="batch"'
```

Exemplo de resposta

{
  "id": "file-batch-xxx",
  "bytes": 231,
  "created_at": 1729065815,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

Faturamento

As operações de arquivo (upload, armazenamento, consulta, exclusão) são gratuitas. Você será cobrado apenas pelos tokens de inferência de modelo (entrada + saída).

Limites de taxa

Limites de taxa: upload (3 QPS), consulta/lista/exclusão (10 QPS combinados).

Ao vivo

• Limpeza periódica: exclua arquivos não utilizados para permanecer abaixo do limite de 10.000 arquivos.

• Verificação de status: Confirme status="processed" antes de usar os arquivos carregados.

• Reconhecimento do limite de taxa: upload (3 QPS), consulta/lista/exclusão (10 QPS). Implemente nova tentativa com espera exponencial.

• Tratamento de erros: trata de tempos limite de rede, erros de API (formato inválido, tamanho excedido) e erros de limite de arquivo. Consulte Códigos de erro.

Perguntas frequentes

1. E se o status do arquivo permanecer "em processamento" após o upload?

O processamento normalmente é concluído em segundos. Se persistir:

• Verifique se o formato do arquivo é compatível.
• Verifique se o tamanho do arquivo está dentro dos limites (extração do arquivo: 150 MB, lote: 500 MB).
• Status da pesquisa com o retrieve API.

2. Os IDs dos arquivos podem ser compartilhados entre contas?

Não. Os IDs de arquivo têm como escopo o QwenCloud conta que os criou.

3. Os arquivos enviados são armazenados permanentemente?

Sim. Os arquivos persistem até você excluí-los.

4. Por que o upload do arquivo falhou?

• Chave de API inválida ou ausente ($DASHSCOPE_API_KEY não definido).
• Formato de arquivo não suportado.
• O tamanho do arquivo excede o limite (extração do arquivo: 150 MB, lote: 500 MB).
• Limite de armazenamento atingido (10.000 arquivos ou 100 GB no total).
• Limite de taxa excedido (3 QPS para upload).

5. Quando devo usar file-extract contra batch?

• file-extract: Análise documental e extração de dados.
• batch: tarefas de inferência em lote (requer formato JSONL).