Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Anleitungen

API Latenz und Download-Durchsatz messen

Führen Sie eine gemessene Suche aus, fassen Sie gespeicherte Proben zusammen oder liefern Sie Zeitmedien an Ihren Speicher.

Auf dieser Seite

Wählen Sie die Messung

MetrischStartseite finish
SuchanfragezeitStarten Sie die HTTP-Anfrage → Lesen Sie den gesamten Text. Verwenden Sie die folgenden Schritte 1–3.
MedienlieferdurchsatzGelieferte Medienbytes ÷ CLI Start-to-Ergebnis-Sekunden. Umfasst Zugriffsprüfungen, Einreichung, Polling und Ergebnisexport.
Async API TimingsAkzeptieren (Anfrage → Job ID) getrennt vom Abschluss (Anfrage → Status abgeschlossen). Verwenden Sie den async-Workflow und behalten Sie das Abfrageintervall bei.

1. Bereiten Sie eine Suchprobe vor

Verwenden Sie Python 3.10+ und einen Schlüssel mit google_search-Berechtigung in FLASHDATA_API_KEY. Es werden keine zusätzlichen Python-Pakete benötigt. Verwenden Sie python3 anstelle von python, wenn dies Ihr Interpretername ist.

Erstellen Sie einen Arbeitsordner. Speichern Sie alle Skripte unten in diesem Ordner und führen Sie ihre Befehle hier aus. Jede neue Suchprobe sendet eine Abfrage ohne automatische Wiederholungen; es gelten die normalen Abfragepreise.

Terminal · Erstellen des Arbeitsordners
mkdir flashdata-benchmark
cd flashdata-benchmark
python --version

Speichern Sie die Anfrage

Speichern Sie dies als request.json in flashdata-benchmark/.

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

2. Zeit für die vollständige Antwort

Speichern Sie measure.py neben request.json. Es kopiert die Anforderung in einen neuen Beispielordner und zeichnet dann die gesamte Antwortzeit, den HTTP-Status, die Anforderung ID und Retry-After auf, wenn es zurückgegeben wird. Socket-Operationen verwenden ein 120-Sekunden-Timeout. Ein vorhandener Beispielordner stoppt die Ausführung, bevor eine Anforderung gesendet wird.

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)

Laufen und inspizieren

Ersetzen Sie die Client-Region durch die Region Ihres Client-Computers, z. B. eu-west-1. Führen Sie den ersten Befehl einmal aus; der zweite Befehl liest nur das gespeicherte Timing.

Eine Suche, dann eine lokale Lesung
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.json

Überprüfen Sie die gespeicherten Dateien

Erfolg endet mit dem Code 0 und zeichnet http_status auf: 200 und outcome: completed. Der Response Body hat status: done und ein Ergebnis-Array. fehlgeschlagene oder unbekannte Exits mit Code 1; prüfen Sie die Dateien, bevor Sie sich für eine andere Abfrage entscheiden.

DateiWas zu überprüfen ist
sample-01/request.jsonDie genaue Eingabe gespeichert vor der Einreichung.
sample-01/response.jsonRaw Response Body; ein HTTP-Fehler kann Nicht-JSON-Inhalte zurückgeben.
sample-01/timing.jsonelapsed_ms, Ergebnis, http_status, request_id und retry_after. Ein null elapsed_ms bedeutet, dass der Prozess keine finish-Aufzeichnung durchgeführt hat.

3. Zusammenfassen von gespeicherten Proben

Speichern Sie summarize.py neben measure.py. Es liest lokale Samples und lehnt doppelte Ordner, unvollständige Timings und nicht übereinstimmende Anforderungseinstellungen, Clientregion oder Python-Version ab.

p50/p95 verwenden Sie die nächstgelegenen Perzentile der abgeschlossenen Antworten. Gescheiterte und unbekannte Versuche bleiben in den Summen. Eine erfolgreiche Probe liefert die gleichen p50 und p95; keine erfolgreichen Proben gibt null für beide.

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))
Lesen Sie die erste Probe
python summarize.py sample-01

Proben absichtlich hinzufügen

Der erste Befehl unten sendet eine weitere Suche. Behalten Sie den gleichen Client-Region-Wert und die gleichen Anforderungseinstellungen bei. Um verschiedene Eingaben zu messen, ändern Sie nur die Abfrage in request.json, bevor Sie sie ausführen. Der Bericht kennzeichnet das Eingabemuster und zählt verschiedene Eingaben.

Für eine Agent-Run-Bewertung vereinbaren Sie zuerst eine Stichprobenzählung und ein Kreditbudget. Führen Sie Samples sequentiell aus; dieses Beispiel zeichnet die Übereinstimmung auf: 1. Speichern Sie die Zusammenfassung mit den Beispielordnern.

Eine zusätzliche Suche
python measure.py request.json sample-02 client-region
Gespeicherte Proben kombinieren · keine neuen Anfragen
python summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.json

Messen Sie die Medienlieferung mit dem CLI

Dieses separate Beispiel liefert eine MP3 an Ihren Speicher. Installieren Sie das CLI, verwenden Sie ein gespeichertes Besitzerprofil mit der youtube_download-Berechtigung und halten Sie das Statusverzeichnis verfügbar. Der Timer verwendet dieses Profil erneut und ignoriert FLASHDATA_API_KEY. Es gelten normale Download-Preise.

Speichern Sie in flashdata-benchmark/ Ihr Ziel als privates storage.json. Dieses S3-Beispiel benötigt Ihre Bucket-, Regions- und Speicheranmeldeinformationen; verwenden Sie Ihre vorhandene private Datei, wenn Sie bereits eine haben.

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

Speichern Sie den Liefer-Timer

Speichern Sie measure-download.py neben storage.json. Es speichert eine neue Ausführung ID vor dem Starten des CLI, wartet bis zu 10 Minuten auf den Befehl und zeichnet die verstrichene Zeit durch den Ergebnisexport auf. Die Wiederverwendung eines Beispielordners wird gestoppt, bevor der CLI gestartet wird.

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)

Eine Lieferung ausführen

Ersetzen Sie die Recherche durch Ihren gespeicherten Profilnamen und Ihre Client-Region durch die Region dieser Maschine. Das Video ID kann durch eines ersetzt werden, das Sie verarbeiten können. Ein abgeschlossener Durchlauf speichert download-01/delivery.json, timing.json und CLI Ausgabedateien.

Der Befehl verwendet das Standard-Verzeichnis des CLI. Wenn ihr profil ein benutzerdefiniertes verzeichnis verwendet, fügen sie den pfad als letztes argument nach der client-region an.

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

Berechnung des Durchsatzes aus gespeicherten Ergebnissen

Speichern Sie throughput.py in flashdata-benchmark/, neben measure-download.py. Es liest die abgeschlossene Lieferung und den Timer von download-01/ aus, ohne Anfragen zu senden. Durchsatz ist die Summe der Medien file_size Werte geteilt durch elapsed_seconds; Mbps verwendet Bytes × 8 ÷ Sekunden ÷ 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))
Lesen Sie die gespeicherte Messung
python throughput.py download-01

Wenn die Lieferung nicht finish

Lesen Sie download-01/cli-error.json und das run_id in timing.json. Verwenden Sie runs show und runs recover mit diesem ID und dem ursprünglichen Profil. Recovery ruft den angenommenen Job ab; halten Sie diesen Versuch aus den Zusammenfassungen des abgeschlossenen Durchsatz heraus, anstatt den Timer neu zu starten oder einen anderen Download einzureichen.

Überprüfen Sie den gespeicherten Versuch · lokale Lesevorgänge
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'))"

Eine Bulk-Sammlung melden

Summieren Sie file_size für abgeschlossene Medienaufzeichnungen und teilen Sie durch die gesamten verstrichenen Sekunden der Sammlung. Auch Aufzeichnung akzeptierte, abgeschlossene und fehlgeschlagene Zählungen, Umfrageintervalle und Pausen. Behalten Sie die Quelle IDs, Ausgabeoptionen und Zielregion mit dem Bericht. Media Retrieval von Ihrem Bucket ist eine separate Messung.