Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

Misurare la latenza API e scaricare il throughput

Eseguire una ricerca misurata, riassumere i campioni salvati, o la consegna dei supporti di tempo al vostro storage.

In questa pagina

Scegli la misura

MetricoIniziare → finish
Tempo di risposta alla ricercaAvviare la richiesta HTTP → leggere il corpo completo. Usa i passaggi 1–3 di seguito.
Media di consegna attraversoputConsegnato media byte ÷ CLI secondi di avvio-risultato. Include controlli di accesso, presentazione, inquinamento ed esportazione di risultati.
Async APIAccettazione record (richiesta → lavoro ID) separatamente dal completamento (richiesta → stato completato). Utilizzare il flusso di lavoro asincastro e mantenere il suo intervallo di polling.

1. Preparare un campione di ricerca

Utilizzare Python 3.10+ e una chiave con il permesso google_search in FLASHDATA_API_KEY. Non sono necessari ulteriori pacchetti Python. Utilizzare python3 invece di pitone se questo è il vostro nome interprete.

Crea una cartella di lavoro. Salvare tutti gli script sottostanti in questa cartella ed eseguire i loro comandi qui. Ogni nuovo campione di ricerca invia una query senza ritiri automatici; si applica il prezzo normale di query.

Terminal · creare la cartella di lavoro
mkdir flashdata-benchmark
cd flashdata-benchmark
python --version

Salvare la richiesta

Salvare questo come request.json dentro flashdata-benchmark/.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

2. Ora la risposta completa

Salvare measure.py accanto a request.json. Copia la richiesta in una nuova cartella del campione, quindi registra il tempo di risposta completo, stato HTTP, richiesta ID e Retry-After quando ritorna. Le operazioni di presa utilizzano un timeout 120-secondo. Una cartella campione esistente arresta l'esecuzione prima di inviare una richiesta.

measure.py
import hashlib
import json
import os
import platform
import sys
import time
from datetime import datetime, timezone
from http.client import HTTPException
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import HTTPRedirectHandler, Request, build_opener

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

if len(sys.argv) != 4:
    raise SystemExit("Usage: python measure.py request.json NEW_DIRECTORY CLIENT_REGION")
key = os.environ.get("FLASHDATA_API_KEY")
if not key:
    raise SystemExit("Set FLASHDATA_API_KEY first")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
if not isinstance(payload, dict) or payload.get("source") != "google_search" \
        or set(payload) - {"source", "query", "params"} \
        or not isinstance(payload.get("query"), str) or not payload["query"].strip() \
        or not isinstance(payload.get("params", {}), dict):
    raise SystemExit("This example measures one realtime google_search request")
body = json.dumps(payload, sort_keys=True, allow_nan=False).encode()
settings = json.dumps({"source": payload["source"], "params": payload.get("params", {})},
    sort_keys=True, allow_nan=False).encode()
folder = Path(sys.argv[2])
try:
    folder.mkdir(mode=0o700)
except FileExistsError:
    raise SystemExit("Sample directory already exists; no request sent. Inspect its saved files.")
(folder / "request.json").write_bytes(body)
request = Request("https://data.flashdata.dev/v1/queries/realtime", data=body,
    headers={"X-API-Key": key, "Content-Type": "application/json", "Accept": "application/json"})
report = {"started_at": datetime.now(timezone.utc).isoformat(),
    "region": sys.argv[3], "source": payload["source"], "mode": "realtime",
    "input_sha256": hashlib.sha256(body).hexdigest(),
    "settings_sha256": hashlib.sha256(settings).hexdigest(), "concurrency": 1,
    "python_version": platform.python_version(), "timeout_seconds": 120,
    "http_status": None, "request_id": None, "retry_after": None,
    "elapsed_ms": None, "outcome": "unknown"}
(folder / "timing.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
raw = b""
start = time.perf_counter()
try:
    try:
        response = build_opener(NoRedirect()).open(request, timeout=120)
    except HTTPError as error:
        response = error
    with response:
        report["http_status"] = response.status
        report["request_id"] = response.headers.get("X-Request-Id")
        report["retry_after"] = response.headers.get("Retry-After")
        raw = response.read()
except (URLError, OSError, HTTPException):
    report["error"] = "transport_error_or_timeout"
report["elapsed_ms"] = round((time.perf_counter() - start) * 1000, 3)
try:
    result = json.loads(raw)
except (ValueError, UnicodeDecodeError):
    result = {}
if report["http_status"] is not None and "error" not in report:
    complete = report["http_status"] == 200 and isinstance(result, dict) \
        and result.get("status") == "done" and isinstance(result.get("results"), list)
    report["outcome"] = "completed" if complete else "failed"
(folder / "response.json").write_bytes(raw)
(folder / "timing.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps(report, indent=2))
raise SystemExit(0 if report["outcome"] == "completed" else 1)

Correre e ispezionare

Sostituire la regione client con la regione della macchina client, come eu-west-1. Eseguire il primo comando una volta; il secondo comando legge solo i tempi salvati.

Una ricerca, poi una lettura locale
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.json

Controllare i file salvati

Il successo esce con il codice 0 e registra http_status: 200 e il risultato: completato. Il corpo di risposta ha status: done e un array di risultati. uscite non riuscite o sconosciute con il codice 1; ispezionare i file prima di decidere su un'altra query.

FileCosa controllare
sample-01/request.jsonL'ingresso esatto salvato prima della presentazione.
sample-01/response.jsonCorpo di risposta raw; un errore HTTP può restituire il contenuto non JSON.
sample-01/timing.jsonelapsed_ms, risultato, http_status, request_id e retry_after. A null elapsed_ms significa che il processo non ha registrato finish.

3. Summarize campioni salvati

Salvare summarize.py accanto a measure.py. Legge i campioni locali e rifiuta le cartelle duplicate, i tempi incompleti e le impostazioni di richiesta errate, la regione client o la versione Python.

p50/p95 utilizza per centoiles di grado più vicino delle risposte completate. I tentativi falliti e sconosciuti rimangono nei totali. Un campione di successo dà lo stesso p50 e p95; nessun campione di successo dà null per entrambi.

summarize.py
import json
import math
import sys
from pathlib import Path

if len(sys.argv) < 2:
    raise SystemExit("Usage: python summarize.py SAMPLE_DIRECTORY [SAMPLE_DIRECTORY ...]")
folders = [Path(value).resolve() for value in sys.argv[1:]]
if len(set(folders)) != len(folders):
    raise SystemExit("Pass each sample directory only once")
rows = [json.loads((folder / "timing.json").read_text(encoding="utf-8")) for folder in folders]
fields = ("source", "mode", "region", "concurrency", "timeout_seconds", "settings_sha256", "python_version")
for row in rows:
    if not isinstance(row, dict) or any(field not in row for field in (*fields, "input_sha256")):
        raise SystemExit("Use timing.json files written by this measure.py")
    elapsed = row.get("elapsed_ms")
    if row.get("outcome") not in ("completed", "failed", "unknown") \
            or type(elapsed) not in (int, float) or not math.isfinite(elapsed) or elapsed < 0:
        raise SystemExit("Incomplete or invalid timing record; inspect it before summarizing")
if len({json.dumps([row[field] for field in fields], sort_keys=True) for row in rows}) != 1:
    raise SystemExit("Compare runs separately when source, mode, region or settings differ")
times = sorted(row["elapsed_ms"] for row in rows if row["outcome"] == "completed")
inputs = len({row["input_sha256"] for row in rows})
def percentile(percent):
    return times[math.ceil(len(times) * percent / 100) - 1] if times else None
print(json.dumps({"context": {field: rows[0][field] for field in fields},
    "attempted": len(rows), "completed": len(times),
    "failed": sum(row["outcome"] == "failed" for row in rows),
    "unknown": sum(row["outcome"] == "unknown" for row in rows),
    "success_rate": len(times) / len(rows), "distinct_inputs": inputs,
    "input_pattern": "repeated_input" if inputs == 1 else "varied_inputs",
    "successful_latency_ms": {"p50": percentile(50), "p95": percentile(95)}}, indent=2))
Leggi il primo campione
python summarize.py sample-01

Aggiungere i campioni deliberatamente

Il primo comando qui sotto invia un'altra ricerca. Mantenere lo stesso valore client-regione e le impostazioni di richiesta. Per misurare i vari input, cambia solo query in request.json prima di eseguirlo. Il rapporto etichetta il modello di input e conta ingressi distinti.

Per una valutazione dell'agente, concordate prima su un conteggio del campione e sul bilancio del credito. Eseguire campioni in modo sequenziale; questo esempio registra concurrency: 1. Salvare il sommario con le cartelle del campione.

Una ricerca aggiuntiva
python measure.py request.json sample-02 client-region
Combina campioni salvati · nessuna nuova richiesta
python summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.json

Misurare la consegna dei supporti con CLI

Questo esempio separato fornisce un MP3 al vostro storage. Installare lo CLI, utilizzare un profilo proprietario salvato con il permesso youtube_download e mantenere la sua directory di stato disponibile. Il timer riutilizza quel profilo e ignora FLASHDATA_API_KEY. Si applica il prezzo normale del download.

In flashdata-benchmark/, salva la tua destinazione come storage.json privato. Questo esempio S3 ha bisogno del tuo secchio, della regione e delle credenziali di archiviazione; usa il tuo file privato esistente se ne hai già uno.

storage.json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}

Salvare il timer di consegna

Salvare measure-download.py accanto a storage.json. Salva una nuova esecuzione ID prima di avviare la CLI, aspetta fino a minuti 10 per il comando, e registra il tempo trascorso attraverso l'esportazione dei risultati. Riutilizzare una cartella di esempio si ferma prima di lanciare il CLI.

measure-download.py
import json
import os
import shutil
import subprocess
import sys
import time
import uuid
from datetime import datetime, timezone
from pathlib import Path

if len(sys.argv) not in (6, 7):
    raise SystemExit("Usage: python measure-download.py VIDEO_ID storage.json NEW_DIRECTORY PROFILE CLIENT_REGION [STATE_DIRECTORY]")
video, storage, directory, profile, region = sys.argv[1:6]
binary = shutil.which("flashdata")
if not binary or not Path(storage).is_file():
    raise SystemExit("Install flashdata on PATH and create the private storage.json first")
folder = Path(directory)
try:
    folder.mkdir(mode=0o700)
except FileExistsError:
    raise SystemExit("Sample directory already exists; inspect timing.json and recover its run_id.")
report = {"run_id": "perf-" + uuid.uuid4().hex, "profile": profile,
    "started_at": datetime.now(timezone.utc).isoformat(),
    "source": "youtube_download", "video_id": video, "output_format": "mp3",
    "region": region, "metric": "cli_start_to_result_saved",
    "timeout_seconds": 600, "elapsed_seconds": None, "outcome": "unknown"}
timing = folder / "timing.json"
timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
print("Saved run_id in " + str(timing), flush=True)
command = [binary, "youtube", "download", video, "--format", "mp3",
    "--storage-config", str(Path(storage).resolve()), "--mode", "async", "--wait",
    "--run-id", report["run_id"], "--output", str(folder / "delivery.json"),
    "--profile", profile, "--timeout", "10m", "--json", "--non-interactive"]
if len(sys.argv) == 7:
    report["state_directory"] = str(Path(sys.argv[6]).resolve())
    command.extend(["--state-dir", report["state_directory"]])
    timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
environment = dict(os.environ)
environment.pop("FLASHDATA_API_KEY", None)  # Reuse the named profile's stored key.
start = time.perf_counter()
with (folder / "cli.json").open("wb") as output, (folder / "cli-error.json").open("wb") as errors:
    try:
        completed = subprocess.run(command, env=environment, stdout=output, stderr=errors,
            timeout=620, check=False)
        report["exit_code"] = completed.returncode
        report["outcome"] = "completed" if completed.returncode == 0 else "not_completed"
    except (OSError, subprocess.TimeoutExpired):
        report["error"] = "process_error_or_timeout"
report["elapsed_seconds"] = time.perf_counter() - start
timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps(report, indent=2))
raise SystemExit(0 if report["outcome"] == "completed" else 1)

Eseguire una consegna

Sostituisci la ricerca con il nome del profilo salvato e la regione del cliente con la regione di questa macchina. Il video ID può essere sostituito con uno che è possibile elaborare. Un'esecuzione completa consente di salvare i file di output download-01/delivery.json, timing.json e CLI.

Il comando utilizza la directory di stato predefinita di CLI. Se il tuo profilo utilizza una directory personalizzata, applica il suo percorso come ultimo argomento, dopo client-region.

Una consegna MP3
python measure-download.py jNQXAC9IVRw storage.json download-01 research client-region
python -m json.tool download-01/timing.json

Calcola il throughput dai risultati salvati

Salva throughput.py in flashdata-benchmark/, accanto a measure-download.py. Si legge la consegna completata e timer da download-01/ senza inviare richieste. Il throughput è la somma dei valori media file_size suddivisi per elapsed_seconds; Mbps utilizza byte × 8 ÷ secondi ÷ 1,000,000.

throughput.py
import json
import math
import sys
from pathlib import Path

if len(sys.argv) != 2:
    raise SystemExit("Usage: python throughput.py SAMPLE_DIRECTORY")
folder = Path(sys.argv[1])
timing = json.loads((folder / "timing.json").read_text(encoding="utf-8"))
if not isinstance(timing, dict) or timing.get("outcome") != "completed" \
        or timing.get("metric") != "cli_start_to_result_saved":
    raise SystemExit("Use a completed sample from measure-download.py")
elapsed = timing.get("elapsed_seconds")
if type(elapsed) not in (int, float) or not math.isfinite(elapsed) or elapsed <= 0:
    raise SystemExit("Missing or invalid elapsed_seconds")
result = json.loads((folder / "delivery.json").read_text(encoding="utf-8-sig"))
if not isinstance(result, dict) or result.get("status") not in ("done", "completed") \
        or result.get("source") != "youtube_download":
    raise SystemExit("Use the completed download result, not a submission or job-status response")
files = result.get("results")
if not isinstance(files, list) or not files or any(not isinstance(item, dict) for item in files):
    raise SystemExit("No delivered media records")
sizes = [item.get("file_size") for item in files]
if any(type(size) not in (int, float) or not math.isfinite(size) or size <= 0 for size in sizes):
    raise SystemExit("Missing or invalid media file_size")
total = sum(sizes)
print(json.dumps({"run_id": timing["run_id"], "metric": timing["metric"],
    "delivered_media_bytes": total, "elapsed_seconds": elapsed,
    "bytes_per_second": total / elapsed, "megabits_per_second": total * 8 / elapsed / 1_000_000}, indent=2))
Leggi la misura salvata
python throughput.py download-01

Se la consegna non è stata finish

Leggi download-01/cli-error.json e run_id in timing.json. Utilizzare runs show e runs recover con ID e il profilo originale. Recupero recupera il lavoro accettato; mantenere questo tentativo di sommari di portata completa, invece di riavviare il timer o di inviare un altro download.

Ispezione del tentativo salvato · letture locali
python -m json.tool download-01/timing.json
python -c "from pathlib import Path; print(Path('download-01/cli-error.json').read_text(encoding='utf-8'))"

Segnala una collezione Bulk

Sum file_size per i record di media completati e dividere per i secondi totali della raccolta. Anche record accettato, conteggi completati e falliti, intervallo di polling e pause. Mantenere la fonte IDs, le opzioni di uscita e la regione di destinazione con il rapporto. Il recupero dei media dal vostro secchio è una misura separata.