Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Panduan pemecahan masalah Inference Gateway
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway"></a>

**Ikhtisar:** HyperPod Inference Gateway merutekan lalu lintas melalui tiga lapisan: Body-Based Router (BBR), gateway dengan`HTTPRoute`, dan Endpoint Picker (EPP). Kesalahan konfigurasi pada setiap lapisan dapat mengakibatkan permintaan gagal, lalu lintas mencapai model yang salah, atau beban yang tidak merata di seluruh pod yang melayani model. Bagian ini mencakup masalah dengan gateway, BBR, gateway dan`HTTPRoute`,, dan EPP`InferencePool`, dan masalah apa pun yang muncul darinya.

## Mendiagnosis status gateway
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-diagnose"></a>

Gunakan perintah berikut untuk memeriksa gateway dan sumber daya yang dikelolanya.

Daftar setiap `InferenceGatewayConfig` sumber daya di seluruh ruang nama:

```
kubectl get inferencegatewayconfig -A
```

Tampilkan status terperinci, status peluncuran per penjadwal, dan pesan kondisi untuk gateway tertentu:

```
kubectl describe inferencegatewayconfig <name> -n <namespace>
```

Periksa pengontrol gateway dan pod Body-Based Router:

```
kubectl get pods -n hyperpod-inference-system
```

Periksa sumber daya perutean hilir yang dihasilkan oleh pengontrol:

```
kubectl get httproute,inferencepool,securitypolicy -A
```

Periksa `status.conditions` dan masing-masing penjadwal `rolloutState` (`Pending`,, `Progressing``Available`, atau`Degraded`). Alasan kegagalan yang dapat ditindaklanjuti ada pada pesan kondisi yang sesuai.

## Add-on masalah instal
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-addon-install"></a>

**Masalah:** Sumber daya gateway hilang, atau tidak `GatewayClass` diterima setelah menginstal add-on HyperPod Inference Amazon EKS.

**Gejala dan resolusi:** `kubectl get gatewayclass inference-gateway` pengembalian`NotFound`, atau sumber daya menunjukkan`ACCEPTED=False`. Ini menunjukkan bahwa add-on tidak diinstal atau instalasi tidak selesai. Instal ulang atau perbarui add-on:

```
aws eks update-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --resolve-conflicts OVERWRITE
```

Kemudian konfirmasikan pengontrol gateway sedang berjalan:

```
kubectl rollout status deploy/inference-gateway-controller \
  -n hyperpod-inference-system --timeout=150s
```

## InferenceGatewayConfig Tidak Menjadi Siap
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-config-not-ready"></a>

**Masalah:** An `InferenceGatewayConfig` dibuat, tetapi `status.conditions` acaranya `Accepted=False` atau`Ready=False`, atau `kubectl apply` ditolak langsung oleh validasi.

**Gejala dan resolusi:**
+ **`kubectl apply`gagal dengan`bbr must be enabled when more than one scheduler is defined`.** Body-Based Router diperlukan setiap kali lebih dari satu penjadwal ditentukan. Atur `spec.bbr.enabled` ke `true`.
+ **`kubectl apply`gagal dengan`modelName must be unique across schedulers`.** Dua penjadwal menyatakan hal yang sama. `modelName` Ganti nama satu sehingga setiap penjadwal memiliki yang berbeda. `modelName`
+ **`Accepted=False`,`Reason=InvalidLoraAdapters`.** Nama adaptor LoRa yang dideklarasikan di bawah `spec.schedulers[].loraAdapters` adalah duplikat di seluruh penjadwal, atau bertabrakan dengan penjadwal. `modelName` Periksa pesan kondisi untuk nama yang menyinggung:

  ```
  kubectl describe inferencegatewayconfig <name> -n <namespace>
  ```
+ **`Accepted=False`,`Reason=ResourceNamingViolation`.** Nama gabungan `<config-name>-<scheduler-name>` melebihi batas label Kubernetes 63 karakter. Persingkat nama konfigurasi atau penjadwal.
+ **`Ready=False`,`Reason=GatewayNotProgrammed`.** Gateway belum menyediakan penyeimbang beban. Periksa Gateway induk:

  ```
  kubectl get gateway -n hyperpod-inference-system
  kubectl describe gateway <name> -n hyperpod-inference-system
  ```
+ **`AdmissionBlocked=True`,`Reason=WebhookDenied`.** Webhook penerimaan cluster menolak pod gateway. Pesan kondisi menamai webhook yang menyinggung. Hapus atau perbaiki webhook, lalu restart Deployment gateway sehingga pod segera dibuat ulang. Nama Deployment dihasilkan, jadi cari dulu:

  ```
  kubectl -n hyperpod-inference-system get deploy \
    -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
  ```

  Kemudian restart:

  ```
  kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>
  ```

## Per-scheduler kegagalan
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-per-scheduler"></a>

**Masalah:** Kondisi penjadwal tertentu (`BackendsReady`,`LoraSupported`, atau`PoolReady`) menunjukkan bahwa penjadwal belum sepenuhnya siap.

**Gejala dan resolusi:**
+ **`BackendsReady=False`, `Reason=NoModelPods` atau`Reason=NoReadyModelPods`.** Tidak ada pod yang cocok`spec.schedulers[].modelSelector`, atau pod yang cocok belum Siap. Bandingkan label pada pod yang melayani model dengan pemilih penjadwal:

  ```
  kubectl get pods -n <namespace> --show-labels
  ```

  Terapkan pod yang melayani model dan tunggu sampai mereka menjadi Siap sebelum menerapkan. `InferenceGatewayConfig`
+ **`BackendsReady=False`,`Reason=InvalidModelSelector`.** Bagian `matchExpressions` bawah `matchLabels` atau di `modelSelector` bawahnya cacat. Perbaiki pemilih di konfigurasi.
+ **`LoraSupported=False`,`Reason=ModelServerLoraDisabled`.** Server model yang mendukung penjadwal ini tidak dimulai dengan dukungan LoRa diaktifkan. Aktifkan flag yang setara pada server model (misalnya, `--enable-lora` untuk VllM) dan restart pod model.
+ **`PoolReady=False`, `Reason=NotFound` atau`Reason=NotAccepted`.** The `InferencePool` or its `HTTPRoute` belum direkonsiliasi atau diterima oleh gateway. Periksa keduanya:

  ```
  kubectl get inferencepool,httproute -n <namespace>
  ```

  Jika salah satu masih hilang beberapa menit setelah konfigurasi diterapkan, jelaskan Gateway induk untuk memeriksa kesalahan penerimaan:

  ```
  kubectl describe gateway -n hyperpod-inference-system
  ```

## Scheduler RolloutState Terdegradasi
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-scheduler-degraded"></a>

**Masalah:** Penerapan Endpoint Picker untuk penjadwal macet dan tidak menjadi Tersedia.

**Gejala dan resolusi:** `EPPReady` Kondisi pada penjadwal membawa alasan yang dapat ditindaklanjuti. Penyebab umum meliputi:
+ Gambar kontainer tidak dapat ditarik.
+ Pod sedang crash looping.
+ Kontainer memiliki kesalahan konfigurasi, seperti variabel lingkungan yang tidak valid, pemasangan volume, atau referensi rahasia.
+ Deployment melebihi batas waktu kemajuannya.

Gunakan perintah berikut untuk mengidentifikasi penjadwal yang gagal dan memeriksa Deployment:

```
# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{range .status.schedulers[?(@.rolloutState=="Degraded")]}{.name}{"\n"}{end}'

# Describe the scheduler's Endpoint Picker Deployment for pod events and container errors
kubectl describe deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>
```

## Titik akhir basi setelah pod model restart
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-stale-endpoint"></a>

**Masalah:** Setelah pod model dihapus dan pod pengganti menjadi Ready, Endpoint Picker terus merutekan ke alamat IP pod yang dihapus. Permintaan mengembalikan HTTP 503 atau koneksi ditolak, dan kondisinya tidak pulih dengan sendirinya.

**Resolusi:** Tambahkan probe kesiapan ke pod model sehingga Kubernetes menandai pod NotReady sebelum IP-nya dihapus dari pool, dan hanya mengiklankan pod pengganti setelah sepenuhnya melayani lalu lintas. Setel `port` ke penjadwal `targetPort` dan `path` ke titik akhir kesehatan server model Anda:

```
readinessProbe:
  httpGet:
    path: /health
    port: 8000
```

**Solusi:** Jika Anda tidak dapat segera menerapkan ulang pod model, restart Endpoint Picker penjadwal untuk memaksanya membangun kembali daftar titik akhir dari kumpulan pod saat ini:

```
kubectl rollout restart deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>
```

## Otentikasi JWT mengembalikan 401 atau 403
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-jwt-auth"></a>

**Masalah:** `spec.auth.jwt` dikonfigurasi dan permintaan ditolak sebelum mencapai model, atau gateway tidak pernah menjadi Siap setelah otentikasi JWT diaktifkan.

**Gejala dan resolusi:**
+ **HTTP 401.** Token hilang, kedaluwarsa, cacat, atau `iss` klaimnya tidak cocok dengan penyedia yang dikonfigurasi. Konfirmasikan klien mengirim `Authorization: Bearer <token>` header, dan memecahkan kode JWT untuk membandingkan klaimnya`iss`. `spec.auth.jwt.provider.issuer`
+ **HTTP 403.** Validasi tanda tangan gagal, atau token `aud` atau `requiredClaims` tidak cocok dengan konfigurasi penyedia. Periksa konfigurasi penyedia dan konfirmasikan token `aud` dan setiap entri yang `requiredClaims` cocok:

  ```
  kubectl get inferencegatewayconfig <name> -n <namespace> \
    -o jsonpath='{.spec.auth.jwt.provider}'
  ```
+ **Gateway tidak pernah menjadi Siap dengan JWT diaktifkan.** `SecurityPolicy`Yang dihasilkan tidak Diterima oleh gateway. Periksa SecurityPolicy sumber daya untuk alasan kegagalan:

  ```
  kubectl get securitypolicy -A
  kubectl describe securitypolicy <name> -n <namespace>
  ```

  Penyebab umum adalah itu tidak dapat `spec.auth.jwt.provider.remoteJWKS.uri` dijangkau dari gateway. Konfirmasikan URI menyelesaikan dan mengembalikan dokumen JWKS yang valid.

## Metrik hilang dari dasbor
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-metrics-missing"></a>

**Masalah:** Metrik Endpoint Picker atau Body-Based Router tidak muncul di dasbor pemantauan Anda.

**Gejala dan resolusi:** Pengumpulan metrik diaktifkan secara default, sehingga sespan OpenTelemetry Kolektor biasanya ada. Konfirmasikan apakah sespan berjalan pada kedua jenis pod, dan apakah metrik dinonaktifkan secara eksplisit.

Periksa sespan pada pod Body-Based Router:

```
kubectl -n hyperpod-inference-system get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```

Periksa sespan pada pod Endpoint Picker:

```
kubectl -n <namespace> get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel
```

Periksa apakah metrik dinonaktifkan secara eksplisit:

```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.observability.metrics.enabled}'
```

Output kosong dari perintah terakhir berarti bidang tidak diatur, dan metrik diaktifkan. Hanya eksplisit yang `false` menonaktifkan sespan. Jika nilainya`false`, atur ke `true` atau hapus bidang, dan pengontrol menyuntikkan sespan pada rekonsiliasi berikutnya.

## Kegagalan permintaan
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-request-failures"></a>

**Masalah:** Gateway sudah Siap, tetapi permintaan inferensi gagal.

**Gejala dan resolusi:**
+ **HTTP 404 untuk model yang dikenal.** `model`Nilai dalam badan permintaan tidak sama persis dengan penjadwal mana pun`modelName`, atau model yang diminta disajikan melalui adaptor LoRa yang tidak dideklarasikan di bawah. `spec.schedulers[].loraAdapters` Jika tidak ada penjadwal yang cocok dengan model yang diminta dan tidak `spec.bbr.defaultBackend` disetel, gateway mengembalikan 404. Verifikasi nama model dan nama adaptor yang dikonfigurasi:

  ```
  kubectl get inferencegatewayconfig <name> -n <namespace> \
    -o jsonpath='{.spec.schedulers[*].modelName}'
  
  kubectl get inferencegatewayconfig <name> -n <namespace> \
    -o jsonpath='{.spec.schedulers[*].loraAdapters}'
  ```
+ **Permintaan hang dan kemudian time out.** Model-serving pod masih memuat bobot model, atau tidak `InferencePool` memiliki titik akhir Siap. Tunggu hingga pod model menjadi Siap sebelum menjalankan titik akhir gateway. Gunakan `modelSelector` label penjadwal dari Anda `InferenceGatewayConfig` sebagai pemilih:

  ```
  kubectl get pods -n <namespace> -l <key>=<value>
  kubectl logs <pod> -n <namespace>
  ```

## Mendebug pemilihan titik akhir
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-debug-scoring"></a>

**Masalah:** Lalu lintas condong ke sejumlah kecil pod model, atau permintaan LoRa dirutekan ke pod yang tidak meng-host adaptor.

**Resolusi:** Tingkatkan verbositas log Endpoint Picker untuk sementara untuk memeriksa keputusan penilaiannya. Setel `logLevel` pada penjadwal:

```
spec:
  schedulers:
    - name: <scheduler-name>
      logLevel: 4
```

Arti tingkat log:
+ `1`- Minta acara siklus hidup.
+ `2`- Default. Peringatan dan penolakan penerimaan.
+ `3`- Ringkasan titik akhir dan per-pencetak gol yang dipilih.
+ `4`- Per-endpoint, skor per pencetak gol dan total tertimbang.
+ `5`- Protocol-level jejak (verbose).

Periksa log Endpoint Picker:

```
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp --tail=200 -f
```

Kembali `logLevel` ke defaultnya saat penyelidikan selesai untuk menghindari volume log berlebih.

## Siklus hidup dan pembersihan
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-lifecycle"></a>

**Masalah:** Menghapus instalasi atau memutakhirkan add-on HyperPod Inference Amazon EKS meninggalkan sumber daya yatim piatu di cluster, atau memblokir instalasi berikutnya.

**Resolusi:** Selalu hapus setiap `InferenceGatewayConfig` sumber daya sebelum menghapus atau memutakhirkan add-on. Menghapus instalasi add-on saat masih `InferenceGatewayConfig` ada menghapus pengontrol yang memiliki finalizer sumber daya, yang membuat sumber daya tersebut macet. `Terminating`

```
kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A
```

Konfirmasikan bahwa perintah kedua tidak mengembalikan baris sebelum melanjutkan operasi add-on.

Setelah menginstal ulang add-on, daftarkan sumber daya di namespace gateway dan hapus apa pun yang tidak lagi dipetakan ke live: `InferenceGatewayConfig`

```
kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
  -n hyperpod-inference-system
```

Sertifikat ACM yang dikeluarkan oleh controller tidak dihapus oleh add-on uninstall. Untuk menghapusnya, filter sertifikat ACM di AWS Resource Groups Tagging API dengan tag `CreatedBy=HyperPodInference` dan hapus sertifikat yang tidak lagi Anda perlukan.

## Kumpulkan log
<a name="sagemaker-hyperpod-model-deployment-ts-inference-gateway-collect-logs"></a>

Gunakan perintah berikut untuk mengambil log dari setiap komponen gateway:

```
# Gateway controller
kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller

# Body-Based Router (deployment name is <gateway-name>-bbr)
kubectl logs -n hyperpod-inference-system deploy/<gateway-name>-bbr -c bbr

# Endpoint Picker for a specific scheduler
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp
```