Azure Cosmos DB Python SDK 的效能秘訣

適用於：NoSQL

重要事項

本文中的效能秘訣僅適用於 Azure Cosmos DB Python SDK。如需詳細資訊，請參閱 Azure Cosmos DB Python SDK 讀我檔案發行備註、套件 (PyPI)、套件 (Conda) 和疑難解答指南。

Azure Cosmos DB 是一個既快速又彈性的分散式資料庫，可在獲得延遲與輸送量保證的情況下順暢地調整。使用 Azure Cosmos DB 時，您不須進行主要的架構變更，或是撰寫複雜的程式碼來調整您的資料庫。相應增加和減少就像進行單一 API 呼叫或 SDK 方法呼叫一樣簡單。不過，由於 Azure Cosmos DB 是透過網路呼叫存取，所以您可以在使用 Azure Cosmos DB Python SDK 時，進行用戶端最佳化以實現最高效能。

因此，如果您是問：「如何改善資料庫效能？」，請考慮下列選項：

網路

為了效能在相同 Azure 區域中共置用戶端

可能的話，請將任何呼叫 Azure Cosmos DB 的應用程式放在與 Azure Cosmos DB 資料庫相同的區域中。以約略的比較來說，在相同區域內對 Azure Cosmos DB 進行的呼叫會在 1-2 毫秒內完成，但美國西岸和美國東岸之間的延遲則會 >50 毫秒。視要求所採用的路由而定，各項要求從用戶端傳遞至 Azure 資料中心界限時的這類延遲可能有所不同。確保呼叫端應用程式與佈建的 Azure Cosmos DB 端點位於相同的 Azure 區域中，將可能達到最低的延遲。如需可用區域的清單，請參閱 Azure 區域。

Azure Cosmos DB 連接原則的圖例。

與多重區域 Azure Cosmos DB 帳戶互動的應用程式必須設定慣用位置，以確保要求會進入共置區域。

啟用加速網路以降低延遲和 CPU 抖動

建議您依照指示，在 Windows (按一下以取得指示) 或 Linux (按一下以取得指示) Azure VM 中啟用加速網路，以求達到最大效能 (降低延遲和 CPU 抖動)。

如果沒有加速網路，在 Azure VM 和其他 Azure 資源之間傳輸的 IO，可能反而會透過位於 VM 和其網路卡之間的主機和虛擬交換器來路由傳送。將主機和虛擬交換器內嵌在資料路徑中，不僅會增加通道的延遲和抖動，還會佔用 VM 的 CPU 週期。使用加速網路時，VM 會直接使用不含中繼的 NIC；由主機和虛擬交換器處理的任何網路原則詳細資料，都會在 NIC 的硬體中加以處理；完全略過主機和虛擬交換器。一般來說可以預期降低延遲並提高輸送量，而且啟用加速網路時，延遲情形會更為一致，CPU 使用率也會降低。

限制：VM OS 必須支援加速網路，而且只有在 VM 停止並解除配置時，才能啟用加速網路。無法使用 Azure Resource Manager 部署 VM。 App Service 未啟用加速網路。

如需詳細資訊，請參閱 Windows 和 Linux 指示。

高可用性

如需在 Azure Cosmos DB 中設定高可用性的一般指導，請參閱 Azure Cosmos DB 中的高可用性。

除了在資料庫平台建立良好的基礎設置之外，您也可以在 Python SDK 中實作分區層級斷路器，有助於處理停機情境。這項功能提供進階機制可用性挑戰，超越預設內建在 SDK 中的跨區域重試功能。這可以大幅提升應用程式的復原能力和效能，特別是在高負載或降級的情況下。

分割區層級斷路器

Python SDK 中的分割區層級斷路器（PPCB）透過追蹤個別實體分割區的健康狀況，並將請求從有問題的分割區導引開，以提升可用性和復原力。這項功能特別適用於處理暫時性和終端機問題，例如網路問題、數據分割升級或移轉。

PPCB 適用於下列情境：

任何一致性層級
分割區索引鍵的作業 (點讀取/寫入)
具有多個讀取區域的單一寫入區域帳戶
多個寫入區域帳戶

運作方式

分割區會根據請求的成功或失敗，通過四種狀態轉換 - 狀況良好、暫定不良、狀況不良、及暫定良好。

失敗追蹤： SDK 會透過一分鐘的時間範圍監視每個分割區的錯誤率（例如 5xx、408）。 SDK 會無限期地追蹤每個分割區的連續失敗。
標示為無法使用： 如果分割區超過設定的臨界值，則會標示為 [狀況不良暫定] ，且從路由中排除 1 分鐘。
升級為狀況不良或復原： 如果復原嘗試失敗，分割區會轉換為 [狀況不良]。經過一段輪詢間隔後，系統會發出暫訂良好探查的限時要求，以確定是否恢復正常。
恢復狀態： 如果暫定探查成功，分割區會返回到正常。否則，它會保持 狀況不良 ，直到下一個探查為止。

此故障轉移由 SDK 內部管理，確保請求會避開已知有問題的分割區，直到確認它們再次恢復正常。

透過環境變數進行設定

您可以使用下列環境變數以控制 PPCB 行為：

變數	說明	預設
`AZURE_COSMOS_ENABLE_CIRCUIT_BREAKER`	啟用/停用 PPCB	`false`
`AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_READ`	標示分割區為無法使用前的最大連續性讀取失敗次數	`10`
`AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_WRITE`	標示分割區為無法使用前的最大連續性寫入失敗次數	`5`
`AZURE_COSMOS_FAILURE_PERCENTAGE_TOLERATED`	標示分割區為無法使用前的失敗百分比閾值	`90`

小提示

未來版本中可能會提供其他設定選項，以微調逾時持續時間和復原退避機制。

排除的區域

排除的區域功能可讓您根據每個請求從慣用位置排除特定區域，從而對請求路由進行精細控制。此功能可在 Azure Cosmos DB Python SDK 4.14.0 版和更新版本中使用。

主要優點：

處理速率限制：當遇到 429（請求過多）回應時，自動將請求路由到具有可用吞吐量的替代區域
目標路由：透過排除所有其他區域來確保從特定區域提供請求
略過偏好順序：在不建立個別用戶端的情況下，覆寫個別要求的預設偏好區域清單

組態：

排除的區域可以在用戶端層級和要求層級進行設定：

from azure.cosmos import CosmosClient
from azure.cosmos.partition_key import PartitionKey

# Configure preferred locations and excluded locations at client level
preferred_locations = ['West US 3', 'West US', 'East US 2']
excluded_locations_on_client = ['West US 3', 'West US']

client = CosmosClient(
    url=HOST,
    credential=MASTER_KEY,
    preferred_locations=preferred_locations,
    excluded_locations=excluded_locations_on_client
)

database = client.create_database('TestDB')
container = database.create_container(
    id='TestContainer',
    partition_key=PartitionKey(path="/pk")
)

# Create an item (writes ignore excluded_locations in single-region write accounts)
test_item = {
    'id': 'Item_1',
    'pk': 'PartitionKey_1',
    'test_object': True,
    'lastName': 'Smith'
}
created_item = container.create_item(test_item)

# Read operations will use preferred_locations minus excluded_locations
# In this example: ['West US 3', 'West US', 'East US 2'] - ['West US 3', 'West US'] = ['East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk']
)

要求層級排除的區域：

** 請求層排除的區域具有最高優先權，並會覆寫用戶端層設定。

# Excluded locations can be specified per request, overriding client settings
excluded_locations_on_request = ['West US 3']

# Create item with request-level excluded regions
created_item = container.create_item(
    test_item,
    excluded_locations=excluded_locations_on_request
)

# Read with request-level excluded regions
# This will use: ['West US 3', 'West US', 'East US 2'] - ['West US 3'] = ['West US', 'East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk'],
    excluded_locations=excluded_locations_on_request
)

微調一致性與可用性

排除的區域功能提供額外的機制，用於平衡應用程式中的一致性和可用性取捨。此功能在需求可能會根據操作條件而變化的動態場景中特別有價值：

動態中斷處理：當主要區域發生中斷且分割區層級斷路器閾值證明不足時，排除的區域可立即容錯移轉，而無需變更程式碼或重新啟動應用程式。與等待自動斷路器啟動相比，這可以更快地回應區域問題。

條件一致性偏好設定：應用程式可以根據操作狀態實作不同的一致性策略：

穩態：排除主要區域以外的所有區域，優先使用主區域進行一致性讀取，確保資料一致性，但可能會降低可用性。
中斷案例：透過允許跨區域路由、接受潛在的資料延遲以換取持續的服務可用性，優先可用性而不是嚴格一致性

此方法可讓外部機制（例如流量管理員或負載平衡器）協調容錯移轉決策，而應用程式則透過區域排除模式來維持對一致性需求的控制。

排除所有區域時，要求會路由傳送至主要/中樞區域。此功能適用於包括查詢在內的所有請求類型，對於維護單一用戶端執行個體在實現靈活路由行為的同時特別有用。

SDK 使用方式

安裝最新的 SDK

Azure Cosmos DB SDK 會持續改善以提供最佳效能。請參閱 Azure Cosmos DB SDK 發行備註，以確定最新的 SDK 並檢閱改善項目。

在應用程式存留期內使用單一 Azure Cosmos DB 用戶端

每個 Azure Cosmos DB 用戶端執行個體都是安全執行緒，並且會有效率地執行連線管理和位址快取處理。若要藉由 Azure Cosmos DB 用戶端獲得有效率的連線管理和更佳的效能，建議在應用程式存留期內，使用 Azure Cosmos DB 用戶端的單一執行個體。

調整逾時和重試設定

您可以根據應用程式需求自訂逾時設定和重試原則。請參閱逾時和重試設定文件，以取得可自訂的設定完整清單。

使用應用程式所需的最低一致性層級

在建立 CosmosClient 時，若在用戶端建立期間未指定任何項目，則會使用帳戶層級一致性。如需一致性層級的詳細資訊，請參閱一致性層級文件。

擴增用戶端工作負載

如果您是以高輸送量層級進行測試，用戶端應用程式可能會成為瓶頸，因為電腦對 CPU 或網路的使用率將達到上限。如果到了這一刻，您可以將用戶端應用程式向外延展至多部伺服器，以繼續將 Azure Cosmos DB 帳戶再往前推進一步。

根據理想的經驗法則，建議不要超過任何指定伺服器上 >50% 的 CPU 使用率，以保持低延遲。

OS 開啟檔案資源限制

某些 Linux 系統 (例如 Red Hat) 有開啟檔案數目的上限，因此有連線總數的上限。執行下列命令來檢視目前的限制：

ulimit -a

開啟檔案 (nofile) 的數目必須夠大，才能有足夠空間供您設定的連線集區大小和 OS 的其他開啟檔案使用。您可以進行修改，以允許較大的連線集區大小。

開啟 limits.conf 檔案：

vim /etc/security/limits.conf

新增/修改下列幾行：

* - nofile 100000

查詢作業

如需查詢作業，請參閱查詢的效能秘訣。

編製索引原則

從索引編製中排除未使用的路徑以加快寫入速度

Azure Cosmos DB 的索引編製原則可讓您利用檢索路徑 (setIncludedPaths 和 setExcludedPaths)，指定要在索引編製中包含或排除的文件路徑。在事先知道查詢模式的案例中，使用檢索路徑可改善寫入效能並降低索引儲存空間，因為檢索成本與檢索的唯一路徑數目直接相互關聯。例如，下列程式碼示範如何使用 "*" 萬用字元，將文件的整個區段 (亦稱為樹狀子目錄) 從索引編製作業中併入和排除。

container_id = "excluded_path_container"
indexing_policy = {
        "includedPaths" : [ {'path' : "/*"} ],
        "excludedPaths" : [ {'path' : "/non_indexed_content/*"} ]
        }
db.create_container(
    id=container_id,
    indexing_policy=indexing_policy,
    partition_key=PartitionKey(path="/pk"))

如需詳細資訊，請參閱 Azure Cosmos DB 索引編製原則。

Throughput

測量和調整較低的要求單位/秒使用量

Azure Cosmos DB 提供許多的資料庫作業，包括使用 UDF、預存程序和觸發程序進行關聯式和階層式查詢，而這些作業全都是對資料庫集合內的文件來進行。與上述各項作業相關聯的成本，會因為完成作業所需的 CPU、IO 和記憶體而不同。您不需要考慮和管理硬體資源，您可以將要求單位 (RU) 想成是執行各種資料庫作業以及服務應用程式要求時所需的資源數量。

輸送量是根據為每個容器所設定的要求單位數量來佈建。要求單位消耗量是以每秒的速率來計算。如果應用程式的速率超過為其容器佈建的要求單位速率，便會受到限制，直到該速率降到容器的佈建層級以下。如果您的應用程式需要較高的輸送量，您可以藉由佈建其他的要求單位來增加輸送量。

查詢的複雜性會影響針對作業所耗用的要求單位數量。述詞數目、述詞性質、UDF 數目，以及來源資料集的大小，全都會影響查詢作業的成本。

若要測量任何作業 (建立、更新或刪除) 的額外負荷，請檢查 x-ms-request-charge 標頭，來測量這些作業所耗用的要求單位數量。

document_definition = {
    'id': 'document',
    'key': 'value',
    'pk': 'pk'
}
document = container.create_item(
    body=document_definition,
)
print("Request charge is : ", container.client_connection.last_response_headers['x-ms-request-charge'])

在此標頭中傳回的要求費用是佈建輸送量的一小部分。例如，如果您佈建了 2000 RU/秒，且前述查詢傳回 1000 份 1 KB 文件，則作業成本會是 1000。因此在一秒內，伺服器在對後續要求進行速率限制前，只會接受兩個這類要求。如需詳細資訊，請參閱要求單位和要求單位計算機。

處理速率限制/要求速率太大

當用戶端嘗試超過帳戶保留的輸送量時，伺服器的效能不會降低，而且不會使用超過保留層級的輸送量容量。伺服器將預先使用 RequestRateTooLarge (HTTP 狀態碼 429) 來結束要求，並傳回 x-ms-retry-after-ms 標頭，以指出使用者重試要求之前必須等候的時間量 (毫秒)。

HTTP Status 429,
Status Line: RequestRateTooLarge
x-ms-retry-after-ms :100

SDK 全都隱含地攔截這個回應，採用伺服器指定的 retry-after 標頭，並重試此要求。除非有多個用戶端同時存取您的帳戶，否則下次重試將會成功。

如果您有多個用戶端都以高於要求速率的方式累積運作，則用戶端在內部設定為 9 的預設重試計數可能會不敷使用；在此情況下，用戶端會擲回 CosmosHttpResponseError (狀態碼 429) 到應用程式。將設定 retry_total 傳遞至用戶端，即可變更預設重試計數。根據預設，如果要求繼續以高於要求速率的方式運作，則會在累計 30 秒的等待時間後傳回 CosmosHttpResponseError (狀態碼 429)。即使目前的重試計數小於最大重試計數 (預設值 9 或使用者定義的值)，也會發生這種情況。

雖然自動重試行為有助於改善大部分應用程式的恢復功能和可用性，但是在進行效能基準測試時可能會有所歧異 (尤其是在測量延遲時)。如果實驗達到伺服器節流並導致用戶端 SDK 以無訊息模式重試，則用戶端觀察到的延遲將會突然增加。若要避免效能實驗期間的延遲尖峰，測量每個作業所傳回的費用，並確保要求是以低於保留要求速率的方式運作。如需詳細資訊，請參閱要求單位。

輸送量較高之少量文件的設計

指定之作業的要求費用 (要求處理成本) 與文件大小直接相互關聯。大型文件的作業成本高於小型文件的作業成本。在理想情況下，架構應用程式和工作流程時，請讓項目大小約為 1KB 或類似的順序或大小。對於注重延遲的應用程式，請避免大型項目，因為好幾 MB 的文件會造成應用程式變慢。

後續步驟

若要深入了解如何針對規模和高效能設計您的應用程式，請參閱 Azure Cosmos DB 的資料分割與調整規模。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？您可以使用現有資料庫叢集的相關資訊進行容量規劃。

如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-04