Khả năng tương thích phiên bản TensorFlow

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tài liệu này dành cho những người dùng cần khả năng tương thích ngược giữa các phiên bản khác nhau của TensorFlow (đối với mã hoặc dữ liệu) và dành cho các nhà phát triển muốn sửa đổi TensorFlow trong khi vẫn duy trì khả năng tương thích.

Phiên bản ngữ nghĩa 2.0

TensorFlow tuân theo Phiên bản ngữ nghĩa 2.0 ( học kỳ ) cho API công khai của nó. Mỗi phiên bản phát hành của TensorFlow có dạng MAJOR.MINOR.PATCH . Ví dụ: TensorFlow phiên bản 1.2.3 có MAJOR phiên bản 1, MINOR phiên bản 2 và PATCH phiên bản 3. Các thay đổi đối với từng số có ý nghĩa như sau:

  • CHÍNH : Các thay đổi không tương thích ngược có thể xảy ra. Mã và dữ liệu hoạt động với bản phát hành chính trước đó sẽ không nhất thiết hoạt động với bản phát hành mới. Tuy nhiên, trong một số trường hợp, các biểu đồ và điểm kiểm tra TensorFlow hiện tại có thể được chuyển sang bản phát hành mới hơn; xem Khả năng tương thích của biểu đồ và điểm kiểm tra để biết chi tiết về khả năng tương thích dữ liệu.

  • NHỎ : Các tính năng tương thích ngược, cải thiện tốc độ, v.v. Mã và dữ liệu hoạt động với bản phát hành nhỏ trước đó chỉ phụ thuộc vào API công khai không thử nghiệm sẽ tiếp tục hoạt động không thay đổi. Để biết chi tiết về những gì là và không phải là API công khai, hãy xem Nội dung được đề cập .

  • PATCH : Sửa lỗi tương thích ngược.

Ví dụ: bản phát hành 1.0.0 đã giới thiệu các thay đổi không tương thích ngược từ bản phát hành 0.12.1. Tuy nhiên, bản phát hành 1.1.1 tương thích ngược với bản phát hành 1.0.0.

Những gì được bảo hiểm

Chỉ các API công khai của TensorFlow mới tương thích ngược giữa các phiên bản nhỏ và bản vá lỗi. Các API công cộng bao gồm

  • Tất cả các hàm và lớp Python được ghi lại trong mô-đun tensorflow và các mô hình con của nó, ngoại trừ

    • Ký hiệu riêng: bất kỳ chức năng, lớp, v.v., có tên bắt đầu bằng _
    • Biểu tượng thử nghiệm và tf.contrib , xem bên dưới để biết chi tiết.

    Lưu ý rằng mã trong các thư mục examples/tools/ không thể truy cập được thông qua mô-đun tensorflow Python và do đó không được bảo đảm về khả năng tương thích.

    Nếu một biểu tượng có sẵn thông qua mô-đun tensorflow Python hoặc các mô-đun con của nó, nhưng không được ghi lại, thì biểu tượng đó không được coi là một phần của API công khai.

  • API tương thích (trong Python, mô-đun tf.compat ). Tại các phiên bản chính, chúng tôi có thể phát hành các tiện ích và điểm cuối bổ sung để giúp người dùng chuyển đổi sang phiên bản chính mới. Các biểu tượng API này không được dùng nữa và không được hỗ trợ (nghĩa là chúng tôi sẽ không thêm bất kỳ tính năng nào và chúng tôi sẽ không sửa lỗi ngoài việc khắc phục các lỗ hổng), nhưng chúng nằm trong phạm vi bảo đảm về khả năng tương thích của chúng tôi.

  • API C.

  • Các tệp đệm giao thức sau:

Những gì không được bảo hiểm

Một số phần của TensorFlow có thể thay đổi theo những cách không tương thích ngược tại bất kỳ thời điểm nào. Bao gồm các:

  • API thử nghiệm : Để tạo điều kiện phát triển, chúng tôi miễn trừ một số ký hiệu API được đánh dấu rõ ràng là thử nghiệm khỏi các đảm bảo về tính tương thích. Cụ thể, những điều sau đây không được bảo đảm về tính tương thích:

    • bất kỳ ký hiệu nào trong mô-đun tf.contrib hoặc các mô-đun con của nó;
    • bất kỳ biểu tượng nào (mô-đun, hàm, đối số, thuộc tính, lớp hoặc hằng số) có tên chứa experimental hoặc Experimental ; hoặc là
    • bất kỳ biểu tượng nào có tên đủ điều kiện bao gồm một mô-đun hoặc lớp mà bản thân nó là thử nghiệm. Điều này bao gồm các trường và thông báo con của bất kỳ bộ đệm giao thức nào được gọi là experimental .
  • Các ngôn ngữ khác : API TensorFlow bằng các ngôn ngữ khác ngoài Python và C, chẳng hạn như:

  • Chi tiết về hoạt động tổng hợp: Nhiều hàm công khai trong Python mở rộng thành một số hoạt động nguyên thủy trong biểu đồ và những chi tiết này sẽ là một phần của bất kỳ biểu đồ nào được lưu vào đĩa dưới dạng GraphDef s. Những chi tiết này có thể thay đổi đối với các bản phát hành nhỏ. Cụ thể, các thử nghiệm hồi quy nhằm kiểm tra sự khớp chính xác giữa các biểu đồ có khả năng bị hỏng giữa các bản phát hành nhỏ, mặc dù hoạt động của biểu đồ sẽ không thay đổi và các điểm kiểm tra hiện tại sẽ vẫn hoạt động.

  • Chi tiết số dấu phẩy động: Các giá trị dấu phẩy động cụ thể được tính toán bởi ops có thể thay đổi bất kỳ lúc nào. Người dùng chỉ nên dựa vào độ chính xác gần đúng và độ ổn định số, không dựa vào các bit cụ thể được tính toán. Các thay đổi đối với công thức số trong các bản phát hành nhỏ và bản vá sẽ dẫn đến độ chính xác tương đương hoặc được cải thiện, với lưu ý rằng trong quá trình học máy, độ chính xác được cải thiện của các công thức cụ thể có thể dẫn đến giảm độ chính xác cho toàn bộ hệ thống.

  • Số ngẫu nhiên: Các số ngẫu nhiên cụ thể được tính toán có thể thay đổi bất cứ lúc nào. Người dùng chỉ nên dựa vào phân phối gần đúng và cường độ thống kê, chứ không phải các bit cụ thể được tính toán. Xem hướng dẫn tạo số ngẫu nhiên để biết chi tiết.

  • Phiên bản sai lệch trong Tensorflow phân tán: Chạy hai phiên bản khác nhau của TensorFlow trong một cụm duy nhất không được hỗ trợ. Không có gì đảm bảo về khả năng tương thích ngược của giao thức dây.

  • Lỗi: Chúng tôi bảo lưu quyền thay đổi hành vi không tương thích ngược (mặc dù không phải API) nếu việc triển khai hiện tại bị hỏng rõ ràng, nghĩa là nếu nó mâu thuẫn với tài liệu hoặc nếu một hành vi dự kiến ​​nổi tiếng và được xác định rõ ràng không được triển khai đúng do đến một lỗi. Ví dụ: nếu trình tối ưu hóa tuyên bố triển khai thuật toán tối ưu hóa nổi tiếng nhưng không khớp với thuật toán đó do lỗi, thì chúng tôi sẽ sửa trình tối ưu hóa đó. Bản sửa lỗi của chúng tôi có thể phá vỡ mã dựa trên hành vi sai đối với sự hội tụ. Chúng tôi sẽ lưu ý những thay đổi như vậy trong ghi chú phát hành.

  • API không sử dụng: Chúng tôi bảo lưu quyền thực hiện các thay đổi không tương thích ngược đối với các API mà chúng tôi không tìm thấy tài liệu sử dụng nào (bằng cách thực hiện kiểm tra việc sử dụng TensorFlow thông qua tìm kiếm GitHub). Trước khi thực hiện bất kỳ thay đổi nào như vậy, chúng tôi sẽ thông báo ý định thực hiện thay đổi trong danh sách gửi thư thông báo@ , cung cấp hướng dẫn về cách giải quyết bất kỳ sự cố nào (nếu có) và chờ hai tuần để cộng đồng của chúng tôi có cơ hội chia sẻ phản hồi của họ .

  • Hành vi có lỗi: Chúng tôi có thể thay thế lỗi bằng hành vi không có lỗi. Chẳng hạn, chúng ta có thể thay đổi một hàm để tính toán kết quả thay vì đưa ra lỗi, ngay cả khi lỗi đó được ghi lại. Chúng tôi cũng có quyền thay đổi nội dung của thông báo lỗi. Ngoài ra, loại lỗi có thể thay đổi trừ khi loại ngoại lệ cho một tình trạng lỗi cụ thể được chỉ định trong tài liệu.

Khả năng tương thích của SavingModels, đồ thị và điểm kiểm tra

SavingModel là định dạng tuần tự hóa ưa thích để sử dụng trong các chương trình TensorFlow. Các mô hình đã lưu chứa hai phần: Một hoặc nhiều biểu đồ được mã hóa dưới dạng GraphDefs và một Điểm kiểm tra. Các biểu đồ mô tả luồng dữ liệu của các hoạt động sẽ được chạy và các điểm kiểm tra chứa các giá trị tenxơ đã lưu của các biến trong biểu đồ.

Nhiều người dùng TensorFlow tạo SavingModels, tải và thực thi chúng với bản phát hành TensorFlow sau này. Tuân thủ semver , Các mô hình đã lưu được viết bằng một phiên bản TensorFlow có thể được tải và đánh giá bằng phiên bản TensorFlow mới hơn với cùng một bản phát hành chính.

Chúng tôi đảm bảo bổ sung cho các Mô hình đã lưu được hỗ trợ . Chúng tôi gọi một SavingModel được tạo chỉ sử dụng các API không dùng nữa, không thử nghiệm, không tương thích trong phiên bản chính của TensorFlow NSavingModel được hỗ trợ trong phiên bản N . Mọi SavingModel được hỗ trợ trong phiên bản chính N +1 của TensorFlow đều có thể được tải và thực thi với phiên bản chính N+1 của TensorFlow. Tuy nhiên, chức năng cần thiết để xây dựng hoặc sửa đổi một mô hình như vậy có thể không còn khả dụng nữa, vì vậy bảo đảm này chỉ áp dụng cho SavingModel chưa sửa đổi.

Chúng tôi sẽ cố gắng duy trì khả năng tương thích ngược càng lâu càng tốt để các tệp được đăng nhiều kỳ có thể sử dụng được trong thời gian dài.

Tương thích GraphDef

Đồ thị được tuần tự hóa thông qua bộ đệm giao thức GraphDef . Để tạo điều kiện thuận lợi cho các thay đổi không tương thích ngược đối với biểu đồ, mỗi GraphDef có một số phiên bản riêng biệt với phiên bản TensorFlow. Ví dụ: GraphDef phiên bản 17 không dùng inv op để thay thế cho reciprocal . Các ngữ nghĩa là:

  • Mỗi phiên bản của TensorFlow hỗ trợ một khoảng các phiên bản GraphDef . Khoảng thời gian này sẽ không đổi trong các bản phát hành bản vá và sẽ chỉ tăng lên trên các bản phát hành nhỏ. Việc ngừng hỗ trợ cho phiên bản GraphDef sẽ chỉ xảy ra đối với bản phát hành chính của TensorFlow (và chỉ phù hợp với hỗ trợ phiên bản được đảm bảo cho SavingModels).

  • Các biểu đồ mới tạo được gán số phiên bản GraphDef mới nhất.

  • Nếu một phiên bản TensorFlow nhất định hỗ trợ phiên bản GraphDef của biểu đồ, thì nó sẽ tải và đánh giá với hành vi giống như phiên bản TensorFlow được sử dụng để tạo ra nó (ngoại trừ các chi tiết số dấu chấm động và số ngẫu nhiên như đã nêu ở trên), bất kể chính phiên bản của TensorFlow. Cụ thể, GraphDef tương thích với tệp điểm kiểm tra trong một phiên bản của TensorFlow (chẳng hạn như trường hợp trong SavingModel) sẽ vẫn tương thích với điểm kiểm tra đó trong các phiên bản tiếp theo, miễn là GraphDef được hỗ trợ.

    Lưu ý rằng điều này chỉ áp dụng cho các Đồ thị được tuần tự hóa trong GraphDefs (và Các mô hình đã lưu): đọc một điểm kiểm tra có thể không đọc được các điểm kiểm tra được tạo bởi cùng một mã chạy một phiên bản TensorFlow khác.

  • Nếu giới hạn trên của GraphDef được tăng lên X trong một bản phát hành (nhỏ), sẽ có ít nhất sáu tháng trước khi giới hạn dưới được tăng lên X. Ví dụ: (chúng tôi đang sử dụng số phiên bản giả định ở đây):

    • TensorFlow 1.2 có thể hỗ trợ GraphDef phiên bản 4 đến 7.
    • TensorFlow 1.3 có thể thêm GraphDef phiên bản 8 và hỗ trợ các phiên bản 4 đến 8.
    • Ít nhất sáu tháng sau, TensorFlow 2.0.0 có thể ngừng hỗ trợ cho các phiên bản từ 4 đến 7, chỉ để lại phiên bản 8.

    Lưu ý rằng vì các phiên bản chính của TensorFlow thường được xuất bản cách nhau hơn 6 tháng, nên đảm bảo cho các Mô hình đã lưu được hỗ trợ nêu chi tiết ở trên mạnh hơn nhiều so với đảm bảo 6 tháng cho GraphDefs.

Cuối cùng, khi hỗ trợ cho phiên bản GraphDef bị ngừng, chúng tôi sẽ cố gắng cung cấp các công cụ để tự động chuyển đổi biểu đồ sang phiên bản GraphDef được hỗ trợ mới hơn.

Khả năng tương thích của đồ thị và điểm kiểm tra khi mở rộng TensorFlow

Phần này chỉ có liên quan khi thực hiện các thay đổi không tương thích đối với định dạng GraphDef , chẳng hạn như khi thêm hoạt động, loại bỏ hoạt động hoặc thay đổi chức năng của các hoạt động hiện có. Phần trước sẽ đủ cho hầu hết người dùng.

Khả năng tương thích ngược và chuyển tiếp một phần

Sơ đồ lập phiên bản của chúng tôi có ba yêu cầu:

  • Khả năng tương thích ngược để hỗ trợ tải biểu đồ và điểm kiểm tra được tạo bằng các phiên bản cũ hơn của TensorFlow.
  • Khả năng tương thích chuyển tiếp để hỗ trợ các tình huống trong đó nhà sản xuất biểu đồ hoặc điểm kiểm tra được nâng cấp lên phiên bản TensorFlow mới hơn trước người tiêu dùng.
  • Cho phép phát triển TensorFlow theo những cách không tương thích. Ví dụ: xóa ops, thêm thuộc tính và xóa thuộc tính.

Lưu ý rằng mặc dù cơ chế phiên bản GraphDef tách biệt với phiên bản TensorFlow, nhưng các thay đổi không tương thích ngược đối với định dạng GraphDef vẫn bị hạn chế bởi Phiên bản ngữ nghĩa. Điều này có nghĩa là chỉ có thể xóa hoặc thay đổi chức năng giữa các phiên bản MAJOR của TensorFlow (chẳng hạn như 1.7 đến 2.0 ). Ngoài ra, khả năng tương thích chuyển tiếp được thực thi trong các bản phát hành Bản vá ( ví dụ: 1.x.1 đến 1.x.2 ).

Để đạt được khả năng tương thích ngược và xuôi, đồng thời biết khi nào cần thực thi các thay đổi về định dạng, biểu đồ và điểm kiểm tra có siêu dữ liệu mô tả thời điểm chúng được tạo. Các phần bên dưới trình bày chi tiết cách triển khai TensorFlow và hướng dẫn để phát triển các phiên bản GraphDef .

Lược đồ phiên bản dữ liệu độc lập

Có các phiên bản dữ liệu khác nhau cho biểu đồ và điểm kiểm tra. Hai định dạng dữ liệu phát triển ở các tốc độ khác nhau và cũng ở các tốc độ khác nhau từ TensorFlow. Cả hai hệ thống tạo phiên bản đều được xác định trong core/public/version.h . Bất cứ khi nào một phiên bản mới được thêm vào, một ghi chú sẽ được thêm vào tiêu đề nêu chi tiết những gì đã thay đổi và ngày tháng.

Dữ liệu, nhà sản xuất và người tiêu dùng

Chúng tôi phân biệt giữa các loại thông tin phiên bản dữ liệu sau:

  • nhà sản xuất : nhị phân sản xuất dữ liệu. Nhà sản xuất có phiên bản ( producer ) và phiên bản dành cho người tiêu dùng tối thiểu mà họ tương thích với ( min_consumer ).
  • người tiêu dùng : nhị phân tiêu thụ dữ liệu. Người tiêu dùng có phiên bản ( consumer ) và phiên bản nhà sản xuất tối thiểu mà họ tương thích với ( min_producer ).

Mỗi phần dữ liệu được tạo phiên bản có trường VersionDef versions VersionDef ghi lại producer đã tạo dữ liệu, min_consumer tương thích với dữ liệu đó và danh sách các phiên bản bad_consumers không được phép.

Theo mặc định, khi nhà sản xuất tạo một số dữ liệu, dữ liệu sẽ kế thừa các phiên bản producermin_consumer của nhà sản xuất. bad_consumers có thể được đặt nếu các phiên bản dành cho người tiêu dùng cụ thể được biết là có lỗi và phải tránh. Người tiêu dùng có thể chấp nhận một phần dữ liệu nếu tất cả những điều sau đây đều đúng:

  • consumer >= min_consumer của dữ liệu
  • producer dữ liệu >= min_producer của người tiêu dùng
  • consumer không có trong dữ liệu của bad_consumers

Vì cả nhà sản xuất và người tiêu dùng đều đến từ cùng một cơ sở mã TensorFlow, nên core/public/version.h chứa phiên bản dữ liệu chính được coi là producer hoặc consumer tùy thuộc vào ngữ cảnh và cả min_consumermin_producer (lần lượt là nhu cầu của nhà sản xuất và người tiêu dùng) . Đặc biệt,

  • Đối với các phiên bản GraphDef , chúng tôi có TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMERTF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Đối với các phiên bản điểm kiểm tra, chúng tôi có TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMERTF_CHECKPOINT_VERSION_MIN_PRODUCER .

Thêm một thuộc tính mới với mặc định cho một op hiện có

Làm theo hướng dẫn bên dưới sẽ chỉ cung cấp cho bạn khả năng tương thích chuyển tiếp nếu tập hợp các hoạt động không thay đổi:

  1. Nếu muốn tương thích về phía trước, hãy đặt strip_default_attrs thành True trong khi xuất mô hình bằng cách sử dụng các phương thức tf.saved_model.SavedModelBuilder.add_meta_graph_and_variablestf.saved_model.SavedModelBuilder.add_meta_graph của lớp SavedModelBuilder hoặc tf.estimator.Estimator.export_saved_model
  2. Thao tác này loại bỏ các thuộc tính có giá trị mặc định tại thời điểm sản xuất/xuất các mô hình. Điều này đảm bảo rằng tf.MetaGraphDef xuất không chứa thuộc tính op mới khi giá trị mặc định được sử dụng.
  3. Việc có quyền kiểm soát này có thể cho phép người tiêu dùng lỗi thời (ví dụ: phân phát các tệp nhị phân chậm hơn các tệp nhị phân đào tạo) tiếp tục tải các mô hình và ngăn chặn sự gián đoạn trong quá trình phân phát mô hình.

Các phiên bản GraphDef đang phát triển

Phần này giải thích cách sử dụng cơ chế lập phiên bản này để thực hiện các loại thay đổi khác nhau đối với định dạng GraphDef .

thêm một op

Thêm op mới cho cả người tiêu dùng và nhà sản xuất cùng một lúc và không thay đổi bất kỳ phiên bản GraphDef nào. Loại thay đổi này tự động tương thích ngược và không ảnh hưởng đến kế hoạch tương thích ngược vì các tập lệnh sản xuất hiện có sẽ không đột nhiên sử dụng chức năng mới.

Thêm một op và chuyển các trình bao bọc Python hiện có để sử dụng nó

  1. Thực hiện chức năng tiêu dùng mới và tăng phiên bản GraphDef .
  2. Nếu có thể làm cho các trình bao bọc chỉ sử dụng chức năng mới trong các trường hợp không hoạt động trước đây, thì các trình bao bọc có thể được cập nhật ngay bây giờ.
  3. Thay đổi trình bao bọc Python để sử dụng chức năng mới. Không tăng min_consumer , vì các mô hình không sử dụng tùy chọn này sẽ không bị hỏng.

Xóa hoặc hạn chế chức năng của op

  1. Sửa tất cả các tập lệnh của nhà sản xuất (không phải bản thân TensorFlow) để không sử dụng op hoặc chức năng bị cấm.
  2. Tăng phiên bản GraphDef và triển khai chức năng tiêu dùng mới cấm hoạt động hoặc chức năng đã loại bỏ đối với GraphDefs ở phiên bản mới trở lên. Nếu có thể, hãy làm cho TensorFlow ngừng tạo GraphDefs với chức năng bị cấm. Để làm như vậy, hãy thêm REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Chờ bản phát hành chính cho mục đích tương thích ngược.
  4. Tăng min_producer lên phiên bản GraphDef từ (2) và loại bỏ hoàn toàn chức năng này.

Thay đổi chức năng của op

  1. Thêm một op tương tự mới có tên SomethingV2 hoặc tương tự và trải qua quá trình thêm nó cũng như chuyển đổi các trình bao bọc Python hiện có để sử dụng nó. Để đảm bảo khả năng tương thích về phía trước, hãy sử dụng các kiểm tra được đề xuất trong compat.py khi thay đổi trình bao bọc Python.
  2. Xóa thao tác cũ (Chỉ có thể thực hiện khi thay đổi phiên bản chính do tính tương thích ngược).
  3. Tăng min_consumer để loại trừ người tiêu dùng với op cũ, thêm lại op cũ làm bí danh cho SomethingV2 và thực hiện quy trình để chuyển các trình bao bọc Python hiện có sang sử dụng nó.
  4. Thực hiện quy trình để xóa SomethingV2 .

Cấm một phiên bản tiêu dùng không an toàn

  1. Bump phiên bản GraphDef và thêm phiên bản xấu vào bad_consumers cho tất cả các GraphDef mới. Nếu có thể, hãy thêm vào bad_consumers chỉ dành cho GraphDefs có chứa một op nhất định hoặc tương tự.
  2. Nếu người tiêu dùng hiện tại có phiên bản xấu, hãy loại bỏ chúng càng sớm càng tốt.