Perfect TensorFlow 简体中文

This project is an experimental wrapper of TensorFlow C API which enables Machine Learning in Server Side Swift.

This package builds with Swift Package Manager and is part of the Perfect project but can also be used as an independent module.

Ensure you have installed and activated the latest Swift 4.1.1 / Xcode 9.3

Project Status

The framework conforms to TensorFlow v1.8.0 C API functionality.

Development Notes

These files are the key part of Perfect-TensorFlow:

Sources
├── PerfectTensorFlow
│   ├── APILoader.swift (1000+ lines, translated from tensorflow/c/c_api.h)
│   ├── PerfectTensorFlow.swift (2700+ lines)
└── TensorFlowAPI
    ├── TensorFlowAPI.c (72 lines)
    └── include
        └── TensorFlowAPI.h (138 lines)

All other Swift sources named as 'pb.*.swift', which is totally up to 45,000+ lines of code, are automatically generated by updateprotos.sh in the root directory. Unfortunately, if using such a script, you still need to manually edit the public typealias part listed in the PerfectTensorFlow.swift.

Up to now there is no such a plan to generate these protocol buffer files dynamically in the Swift Source since Perfect-TensorFlow is a part of Perfect, although it can run independently, all features of Perfect framework are built by Swift Package Manager for consistency consideration. However, since the project is also fast growing, all pull request, ideas, suggestions and comments are welcome!

API Guide

API programming topics can be found in Perfect TensorFlow Guide.

Also, there are many features that has already embedded in the testing script, such as TensorFlow event and summary for TensorBoard report and benchmarking. Please check the Perfect TensorFlow Testing Script for detail.

Quick Start

TensorFlow C API Library Installation

Perfect-TensorFlow is based on TensorFlow C API, i.e., libtensorflow.so and libtensorflow_framework.so on runtime. This project contains an express CPU version installation script for this module on both macOS / Ubuntu Linux, and will install both dynamic libraries into path /usr/local/lib. You can download & run install.sh. Before running this script, please make sure that curl has been installed onto your computer.

For more installation options, such as GPU/CPU and multiple versions on the same machine, please check TensorFlow website: Installing TensorFlow for C

Perfect TensorFlow Application

To use this library, add dependencies to your project's Package.swift with the LATEST TAG:

.package(url: "https://github.com/PerfectlySoft/Perfect-TensorFlow.git", from: "1.4.0")

and it also requires a dependency declaration in the same file, target section:

dependencies: ["PerfectTensorFlow"]

Then declare the library:

// TensorFlowAPI contains most API functions defined in libtensorflow.so
import TensorFlowAPI

// This is the Swift version of TensorFlow classes and objects
import PerfectTensorFlow

// To keep the naming consistency with TensorFlow in other languages such as
// Python or Java, making an alias of `TensorFlow` Class is a good idea:
public typealias TF = TensorFlow

Library Activation

⚠️NOTE⚠️ Prior to use ANY ACTUAL FUNCTIONS of Perfect TensorFlow framework, TF.Open() must be called first:

// this action will load all api functions defined
// in /usr/local/lib/libtensorflow.so
try TF.Open()

Please also note that you can active the library with a specific path, alternatively, especially in case of different versions or CPU/GPU library adjustment required:

// this action will load the library with the path
try TF.Open("/path/to/DLL/of/libtensorflow.so")

"Hello, Perfect TensorFlow!"

Here is the Swift version of "Hello, TensorFlow!":

// define a string tensor
let tensor = try TF.Tensor.Scalar("Hello, Perfect TensorFlow! 🇨🇳🇨🇦")

// declare a new graph
let g = try TF.Graph()

// turn the tensor into an operation
let op = try g.const(tensor: tensor, name: "hello")

// run a session
let o = try g.runner().fetch(op).addTarget(op).run()

// decode the result      
let decoded = try TF.Decode(strings: o[0].data, count: 1)

// check the result
let s2 = decoded[0].string
print(s2)

Matrix Operations

As you can see, Swift version of TensorFlow keeps the same principals of the original one, i.e., create tensors, save tensors into graph, define the operations and then run the session & check the result.

Here is an other simple example of matrix operations in Perfect TensorFlow:

/* Matrix Multiply:
| 1 2 |   |0 1|   |0 1|
| 3 4 | * |0 0| = |0 3|
*/
// input the matrix.
let tA = try TF.Tensor.Matrix([[1, 2], [3, 4]])
let tB = try TF.Tensor.Matrix([[0, 0], [1, 0]])

// adding tensors to graph
let g = try TF.Graph()
let A = try g.const(tensor: tA, name: "Const_0")
let B = try g.const(tensor: tB, name: "Const_1")

// define matrix multiply operation
let v = try g.matMul(l: A, r: B, name: "v", transposeB: true)

// run the session
let o = try g.runner().fetch(v).addTarget(v).run()
let m:[Float] = try o[0].asArray()
print(m)
// m shall be [0, 1, 0, 3]

Load a Saved Artificial Neural Network Model

Besides building graph & sessions in code, Perfect TensorFlow also provides a handy method to load models into runtime, i.e, generate a new session by loading a model file:

let g = try TF.Graph()

// the meta signature info defined in a saved model
let metaBuf = try TF.Buffer()

// load the session
let session = try g.load(
	exportDir: "/path/to/saved/model",
	tags: ["tag1", "tag2", ...],
	metaGraphDef: metaBuf)

Computer Vision Demo

A detailed example of Perfect TensorFlow for Computer Vision can be found in this repo: Perfect TensorFlow Demo, where you can upload any local images or draw a scribble online to test if the server can recognize the picture content:

Further Information

For more information on the Perfect project, please visit perfect.org.

PerfectlySoft / Perfect-TensorFlow