learner.h

前往此文件文档。

 
#ifndef XGBOOST_LEARNER_H_
#define XGBOOST_LEARNER_H_
 
#include <dmlc/io.h> // 用于 Serializable
#include <xgboost/base.h> // 用于 bst_feature_t, bst_target_t, bst_float, Args, GradientPair, ..
#include <xgboost/context.h> // 用于 Context
#include <xgboost/linalg.h> // 用于 Vector, VectorView
#include <xgboost/metric.h> // 用于 Metric
#include <xgboost/model.h> // 用于 Configurable, Model
#include <xgboost/span.h> // 用于 Span
#include <xgboost/task.h> // 用于 ObjInfo
 
#include <algorithm> // 用于 max
#include <cstdint> // 用于 int32_t, uint32_t, uint8_t
#include <map> // 用于 map
#include <memory> // 用于 shared_ptr, unique_ptr
#include <string> // 用于 string
#include <utility> // 用于 move
#include <vector> // 用于 vector
 
namespace xgboost {
class FeatureMap;
class Metric;
class GradientBooster;
class ObjFunction;
class DMatrix;
class Json;
struct XGBAPIThreadLocalEntry;
template <typename T>
class HostDeviceVector;
class CatContainer;
 
enum class PredictionType : std::uint8_t { // NOLINT
 kValue = 0,
 kMargin = 1,
 kContribution = 2,
 kApproxContribution = 3,
 kInteraction = 4,
 kApproxInteraction = 5,
 kLeaf = 6
};
 
class Learner : public Model, public Configurable, public dmlc::Serializable {
 public
 ~Learner() override;
 virtual void Configure() = 0;
 virtual void UpdateOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train) = 0;
 virtual void BoostOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train,
 linalg::Matrix<GradientPair>* in_gpair) = 0;
 virtual std::string EvalOneIter(int iter,
 const std::vector<std::shared_ptr<DMatrix>>& data_sets,
 const std::vector<std::string>& data_names) = 0;
 virtual void Predict(std::shared_ptr<DMatrix> data, bool output_margin,
 HostDeviceVector<bst_float>* out_preds, bst_layer_t layer_begin,
 bst_layer_t layer_end, bool training = false, bool pred_leaf = false,
 bool pred_contribs = false, bool approx_contribs = false,
 bool pred_interactions = false) = 0;
 
 virtual void InplacePredict(std::shared_ptr<DMatrix> p_m, PredictionType type, float missing,
 HostDeviceVector<float>** out_preds, bst_layer_t layer_begin,
 bst_layer_t layer_end) = 0;
 
 virtual void CalcFeatureScore(std::string const& importance_type,
 common::Span<int32_t const> trees,
 std::vector<bst_feature_t>* features,
 std::vector<float>* scores) = 0;
 
  /*
 * \brief 从梯度提升器获取提升轮数。
   */
 virtual int32_t BoostedRounds() const = 0;
 virtual std::uint32_t Groups() const = 0;
 
 void LoadModel(Json const& in) override = 0;
 void SaveModel(Json* out) const override = 0;
 
 virtual void SetParams(Args const& args) = 0;
 virtual void SetParam(const std::string& key, const std::string& value) = 0;
 
 virtual bst_feature_t GetNumFeature() const = 0;
 
 virtual void SetAttr(const std::string& key, const std::string& value) = 0;
 virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
 virtual bool DelAttr(const std::string& key) = 0;
 virtual std::vector<std::string> GetAttrNames() const = 0;
 virtual void SetFeatureNames(std::vector<std::string> const& fn) = 0;
 virtual void GetFeatureNames(std::vector<std::string>* fn) const = 0;
 virtual void SetFeatureTypes(std::vector<std::string> const& ft) = 0;
 virtual void GetFeatureTypes(std::vector<std::string>* ft) const = 0;
 [[nodiscard]] virtual CatContainer const* Cats() const = 0;
 virtual Learner* Slice(bst_layer_t begin, bst_layer_t end, bst_layer_t step,
 bool* out_of_bound) = 0;
 virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
 bool with_stats,
 std::string format) = 0;
 
 virtual XGBAPIThreadLocalEntry& GetThreadLocal() const = 0;
 virtual void Reset() = 0;
 static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
 virtual Context const* Ctx() const = 0;
 virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;
 
 protected
 std::unique_ptr<ObjFunction> obj_;
 std::unique_ptr<GradientBooster> gbm_;
 std::vector<std::unique_ptr<Metric> > metrics_;
 Context ctx_;
};
 
struct LearnerModelParamLegacy;
 
enum class MultiStrategy : std::int32_t {
 kOneOutputPerTree = 0,
 kMultiOutputTree = 1,
};
 
struct LearnerModelParam {
 private
 linalg::Vector<float> base_score_;
 
 LearnerModelParam(LearnerModelParamLegacy const& user_param, ObjInfo t,
 MultiStrategy multi_strategy);
 
 public
 bst_feature_t num_feature{0};
 std::uint32_t num_output_group{0};
 ObjInfo task{ObjInfo::kRegression};
 MultiStrategy multi_strategy{MultiStrategy::kOneOutputPerTree};
 
 LearnerModelParam() = default;
 LearnerModelParam(Context const* ctx, LearnerModelParamLegacy const& user_param,
 linalg::Vector<float> base_score, ObjInfo t, MultiStrategy multi_strategy);
 // 此构造函数仅用于测试。
 LearnerModelParam(bst_feature_t n_features, linalg::Vector<float> base_score,
 std::uint32_t n_groups, bst_target_t n_targets, MultiStrategy multi_strategy)
 : base_score_{std::move(base_score)},
 num_feature{n_features},
 num_output_group{std::max(n_groups, n_targets)},
 multi_strategy{multi_strategy} {}
 
 linalg::VectorView<float const> BaseScore(Context const* ctx) const;
 [[nodiscard]] linalg::VectorView<float const> BaseScore(DeviceOrd device) const;
 
 void Copy(LearnerModelParam const& that);
 [[nodiscard]] bool IsVectorLeaf() const noexcept {
 return multi_strategy == MultiStrategy::kMultiOutputTree;
  }
 [[nodiscard]] bst_target_t OutputLength() const noexcept { return this->num_output_group; }
 [[nodiscard]] bst_target_t LeafLength() const noexcept {
 return this->IsVectorLeaf() ? this->OutputLength() : 1;
  }
 
 /* \brief 此参数是否已使用 LearnerModelParamLegacy 初始化。 */
 [[nodiscard]] bool Initialized() const { return num_feature != 0 && num_output_group != 0; }
};
 
} // namespace xgboost
#endif // XGBOOST_LEARNER_H_